chore(claude): set up workspace rules and code conventions (Step 0)
Bootstrap Claude Code Spec-Driven Development: - .claude/settings.json: allow safe bash (cd, ls, find, cat, mkdir), deny .env/secrets and destructive git/rm commands - .claude/rules/: markdown, file-paths, commits, error-handling, dev-guidelines (mirrors Salestech Products Development Guidelines) - .claude/onboarding/step0_preparation/01_code_conventions.md: document the configuration applied - .gitignore: track project-level .claude/ config; keep settings.local.json and .codegraph/ ignored
This commit is contained in:
Dominik Seemann
parent
62648289d1
commit
44eb4588bf
|
|
@ -0,0 +1,76 @@
|
||||||
|
# Step 0 — Code Conventions & Rules
|
||||||
|
|
||||||
|
Documentation of the rules and code conventions configured during the
|
||||||
|
Claude Code workspace setup (Step 0).
|
||||||
|
|
||||||
|
## Context
|
||||||
|
- **Project:** MiroFish — Multi-Agent Swarm Intelligence Prediction Engine
|
||||||
|
- **Stack:** Python (Flask, uv) backend + Vue 3 / Vite frontend
|
||||||
|
- **Date applied:** 2026-05-06
|
||||||
|
|
||||||
|
## What Was Configured
|
||||||
|
|
||||||
|
### 1. `.claude/settings.json` — Permissions
|
||||||
|
**Always allow (bash):**
|
||||||
|
- `cd:*`
|
||||||
|
- `ls:*`
|
||||||
|
- `find:*`
|
||||||
|
- `cat:*`
|
||||||
|
- `mkdir:*`
|
||||||
|
|
||||||
|
**Always deny (Read / Write / Edit):**
|
||||||
|
- `*/.env*`
|
||||||
|
- `*/secrets/*`
|
||||||
|
|
||||||
|
**Always deny (bash):**
|
||||||
|
- `rm -f*`
|
||||||
|
- `rm -rf*`
|
||||||
|
- `git push -f*`
|
||||||
|
- `git push --force*`
|
||||||
|
|
||||||
|
This protects secrets and forbids destructive Git / filesystem
|
||||||
|
operations while allowing safe navigation and inspection commands.
|
||||||
|
|
||||||
|
### 2. `.claude/rules/` — Rule Files
|
||||||
|
|
||||||
|
| File | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `markdown.md` | Adhere to standard Markdown syntax (markdownguide.org). |
|
||||||
|
| `file-paths.md` | Always wrap file paths in quotes; use a generic placeholder path in docs/examples. |
|
||||||
|
| `commits.md` | Conventional Commits standard; never add `Co-Authored-By:` watermarks. |
|
||||||
|
| `error-handling.md` | When an error occurs, offer to save it as a rule. |
|
||||||
|
| `dev-guidelines.md` | Salestech Products Development Guidelines (live source on Notion). |
|
||||||
|
|
||||||
|
### 3. Salestech Development Guidelines
|
||||||
|
- **Notion source (authoritative):** https://candylabs.notion.site/development-guidelines
|
||||||
|
- A summary snapshot is stored in `.claude/rules/dev-guidelines.md`.
|
||||||
|
- Always consult the live document via the Notion MCP server for the
|
||||||
|
latest version.
|
||||||
|
- Snapshot covers: formatting & style, naming, comments,
|
||||||
|
Git workflow, React & TypeScript, Tailwind 4, folder structure,
|
||||||
|
accessibility, environments / secrets / dependencies, security,
|
||||||
|
infrastructure, enforcement.
|
||||||
|
|
||||||
|
### 4. Commit Watermarks
|
||||||
|
- `Co-Authored-By:` blocks must **never** be added to commits
|
||||||
|
(matches §4.2 of the dev guidelines: *"Avoid 'watermarks' like
|
||||||
|
'co-authored by Claude'"*).
|
||||||
|
|
||||||
|
## Manual Setup Items (Not Automated)
|
||||||
|
The following items in Step 0 are user / environment setup and are
|
||||||
|
**not** performed by this onboarding pass — they must be completed by
|
||||||
|
the developer:
|
||||||
|
|
||||||
|
1. **Claude Code clients**
|
||||||
|
- Claude Desktop, Claude Code CLI, VSCode extension
|
||||||
|
2. **MCP servers** (run from terminal, not from inside Claude)
|
||||||
|
- Notion: `claude mcp add --transport http notion https://mcp.notion.com/mcp`
|
||||||
|
- Atlassian: `claude mcp add --transport http atlassian https://mcp.atlassian.com/v1/mcp`
|
||||||
|
- Figma: `claude mcp add --transport http figma-remote-mcp https://mcp.figma.com/mcp`
|
||||||
|
- Authenticate each via `/mcp` in Claude after restart.
|
||||||
|
3. **Basics**
|
||||||
|
- Node.js (https://nodejs.org/en) — required for CC-SDD.
|
||||||
|
- Git + GitHub CLI (`gh auth login`) — required for PRs.
|
||||||
|
|
||||||
|
## Next
|
||||||
|
- Step 1: Prepare the codebase (CLAUDE.md, README.md, structure)
|
||||||
|
|
@ -0,0 +1,47 @@
|
||||||
|
# Commit Rules
|
||||||
|
|
||||||
|
Whenever committing, use the **Conventional Commits** standard.
|
||||||
|
|
||||||
|
## Format
|
||||||
|
```
|
||||||
|
<type>(<scope>): <short summary>
|
||||||
|
|
||||||
|
<optional body>
|
||||||
|
|
||||||
|
<optional footer>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Types
|
||||||
|
- `feat` — A new feature
|
||||||
|
- `fix` — A bug fix
|
||||||
|
- `docs` — Documentation only changes
|
||||||
|
- `style` — Changes that do not affect meaning (whitespace, formatting)
|
||||||
|
- `refactor` — Code change that neither fixes a bug nor adds a feature
|
||||||
|
- `test` — Adding or correcting tests
|
||||||
|
- `chore` — Build process, tooling, configuration
|
||||||
|
- `ci` — CI / CD configuration changes
|
||||||
|
- `perf` — Performance improvement
|
||||||
|
|
||||||
|
## Rules
|
||||||
|
- **Type** is required and must be lowercase.
|
||||||
|
- **Summary** must be lowercase, in imperative mood, max 72 characters,
|
||||||
|
no trailing period.
|
||||||
|
- **Body** (if present) explains *what* and *why*, not *how*.
|
||||||
|
- **Footer** can reference tickets (e.g., `Closes PROJ-1234`).
|
||||||
|
- **Never** add a `Co-Authored-By:` block (no Claude/AI watermarks).
|
||||||
|
- Avoid mixing unrelated changes in a single commit.
|
||||||
|
- Never commit secrets, credentials, or environment files.
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
```
|
||||||
|
feat(auth): add two-factor authentication flow
|
||||||
|
|
||||||
|
Implements TOTP-based 2FA using the authenticator app.
|
||||||
|
Users can enable/disable 2FA from their security settings.
|
||||||
|
|
||||||
|
Closes PROJ-1234
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
fix(cart): prevent duplicate items on rapid clicks
|
||||||
|
```
|
||||||
|
|
@ -0,0 +1,131 @@
|
||||||
|
# Salestech Products Development Guidelines
|
||||||
|
|
||||||
|
Always obey the **Salestech Products Development Guidelines**. These are
|
||||||
|
enforceable rules — non-compliant code will be rejected during review.
|
||||||
|
|
||||||
|
## Source
|
||||||
|
- Notion (Live, authoritative): https://candylabs.notion.site/development-guidelines
|
||||||
|
- Connect via Notion MCP server (HTTP requires JS, so MCP is the only reliable way).
|
||||||
|
- Always consult the live document for the latest version.
|
||||||
|
|
||||||
|
## Summary (snapshot — refer to live doc for authority)
|
||||||
|
|
||||||
|
### 1. Code Formatting & Style
|
||||||
|
- 4 spaces indentation (JS/TS and Python). No tabs.
|
||||||
|
- Max **120 chars** per line.
|
||||||
|
- No trailing whitespace; files end with a single newline.
|
||||||
|
- JS/TS: no semicolons (`semi: false`), single quotes, trailing commas
|
||||||
|
where valid in ES5, omit parens around single arrow params.
|
||||||
|
- Python: double quotes for strings.
|
||||||
|
- Tools: Prettier + ESLint (JS/TS, npm); Ruff (Python, uv).
|
||||||
|
|
||||||
|
### 2. Naming
|
||||||
|
- JS/TS: `camelCase` vars/funcs, `PascalCase` classes/types/enums,
|
||||||
|
`UPPER_SNAKE_CASE` constants, `kebab-case` filenames, boolean prefixes
|
||||||
|
`is`/`has`/`should`.
|
||||||
|
- Python: `snake_case` vars/funcs/files, `PascalCase` classes,
|
||||||
|
`UPPER_SNAKE_CASE` constants, `_leading_underscore` private.
|
||||||
|
- No abbreviations (except `id`, `url`, `http`).
|
||||||
|
- No single-letter vars (except short lambda / loop indices).
|
||||||
|
- No Hungarian notation.
|
||||||
|
|
||||||
|
### 3. Comments & Documentation
|
||||||
|
- Don't comment the obvious — comment the *why*.
|
||||||
|
- `TODO:` / `FIXME:` must include a ticket reference.
|
||||||
|
- JS/TS: JSDoc on all exported functions, classes, interfaces.
|
||||||
|
- Python: Google-style docstrings on all public funcs/classes/modules.
|
||||||
|
|
||||||
|
### 4. Git Workflow
|
||||||
|
- Branch: `<type>/<ticket-id>-<short-description>` (`feat`, `fix`,
|
||||||
|
`chore`, `docs`, `hotfix`).
|
||||||
|
- Commits: **Conventional Commits**, lowercase, imperative, max 72 chars,
|
||||||
|
no period, no `Co-Authored-By:` watermarks.
|
||||||
|
- PRs: linked to a ticket, ≥1 human approval, all CI checks pass,
|
||||||
|
squash-merge feature branches, delete source branch after merge.
|
||||||
|
- Never commit directly to `main` / `dev`; never force-push shared
|
||||||
|
branches; never commit secrets.
|
||||||
|
|
||||||
|
### 5. React & TypeScript
|
||||||
|
- Component file order: imports → types → constants → helpers →
|
||||||
|
component.
|
||||||
|
- Named exports only; function declarations for components.
|
||||||
|
- Props types named `<ComponentName>Props`; never `React.FC`.
|
||||||
|
- Hooks start with `use`; never call hooks conditionally.
|
||||||
|
- React Router v7: file/config-based routes (don't mix), use
|
||||||
|
`loader`/`action`, `useNavigate`, `useSearchParams`, `<Link>`,
|
||||||
|
`<Outlet>`.
|
||||||
|
- TanStack Query: centralized query key factories, never `fetch`/`axios`
|
||||||
|
in components, always handle loading/success/error, prefer
|
||||||
|
`invalidateQueries` over manual cache.
|
||||||
|
- State priority: URL → TanStack Query → component state → Context.
|
||||||
|
Never duplicate server state into local state.
|
||||||
|
|
||||||
|
### 6. Tailwind 4 (CSS-only config)
|
||||||
|
- Component styles inline as Tailwind classes; no separate CSS modules
|
||||||
|
per component.
|
||||||
|
- Use `clsx` for dynamic classes.
|
||||||
|
- Mobile-first responsive prefixes.
|
||||||
|
- `prettier-plugin-tailwindcss` ordering required.
|
||||||
|
- No `!important` (Tailwind `!`) without justification + comment.
|
||||||
|
- `main.css` only for `@import`, `@theme`, global base styles, third-
|
||||||
|
party overrides.
|
||||||
|
|
||||||
|
### 7. Folder Structure
|
||||||
|
- Layer-based for frontend (`api/`, `components/`, `hooks/`,
|
||||||
|
`pages/`, `queries/`, `routes/`, `types/`, `utils/`).
|
||||||
|
- FastAPI: `routers/`, `models/`, `schemas/`, `services/`; Pydantic
|
||||||
|
`BaseSettings`; business logic in services not routers.
|
||||||
|
- Django: `config/`, `apps/<app>/`, `common/`; one app per domain;
|
||||||
|
business logic in `services.py`; max one migration per app per PR;
|
||||||
|
custom User model from day 1.
|
||||||
|
- Django templates: `snake_case.html` in `templates/<app_name>/`,
|
||||||
|
partials prefixed `_`, `{% extends %}` mandatory, DjHTML formatter,
|
||||||
|
`{% url %}` for all URLs.
|
||||||
|
- Root directory: configuration files only.
|
||||||
|
- README.md mandatory (setup, env vars, run/test).
|
||||||
|
|
||||||
|
### 8. Accessibility
|
||||||
|
- WCAG 2.1 Level AA.
|
||||||
|
- Semantic HTML; one `<h1>` per page; no skipped heading levels.
|
||||||
|
- All images need `alt`; decorative use `alt=""`.
|
||||||
|
- 4.5:1 / 3:1 contrast minimums.
|
||||||
|
- Every form input: visible `<label>` linked via `htmlFor`/`id`.
|
||||||
|
- Keyboard accessible; native `<button>` for actions, `<a>`/`<Link>`
|
||||||
|
for navigation.
|
||||||
|
- Custom widgets: implement WAI-ARIA pattern + keyboard handling.
|
||||||
|
- Modals trap focus and restore on close.
|
||||||
|
|
||||||
|
### 9. Environments, Secrets, Dependencies
|
||||||
|
- `.env` never committed; `.env.example` always provided and current.
|
||||||
|
- Client-exposed vars use framework prefix (e.g., `VITE_`).
|
||||||
|
- Never commit / log secrets. Rotate immediately if leaked.
|
||||||
|
- Verify a new dep is necessary; prefer well-maintained, MIT/Apache/BSD.
|
||||||
|
- No trivial deps (`is-odd`, `left-pad`, etc.).
|
||||||
|
- Lock files always committed, exact versions, no `latest` ranges.
|
||||||
|
- Dev dependencies separated from production.
|
||||||
|
|
||||||
|
### 10. Security
|
||||||
|
- Validate/sanitize all user input on the server.
|
||||||
|
- Parameterize all DB queries.
|
||||||
|
- Auto-escape templating; no `dangerouslySetInnerHTML` / `| safe`
|
||||||
|
without lead approval.
|
||||||
|
- AuthN/AuthZ on every endpoint.
|
||||||
|
- HTTPS only (except `localhost`).
|
||||||
|
- Security headers: CSP, X-Content-Type-Options, HSTS, X-Frame-Options.
|
||||||
|
- CSRF protection (Django middleware / secure token storage on SPA).
|
||||||
|
- Rate-limit auth endpoints + public APIs.
|
||||||
|
- Never log passwords/tokens/PII.
|
||||||
|
- Principle of least privilege for service accounts.
|
||||||
|
|
||||||
|
### 11. Infrastructure
|
||||||
|
- `compose.yaml` (no `version:` key) for Docker Compose.
|
||||||
|
|
||||||
|
### 12. Enforcement
|
||||||
|
- Pre-commit hooks: format, lint, import order.
|
||||||
|
- CI: tests, lint, type check, build, dep audit.
|
||||||
|
- Code review: naming, docs, architecture, a11y.
|
||||||
|
- Non-compliance is grounds for requesting changes.
|
||||||
|
|
||||||
|
---
|
||||||
|
**When in doubt, fetch the latest version from Notion via the MCP server
|
||||||
|
and follow it — these guidelines evolve.**
|
||||||
|
|
@ -0,0 +1,23 @@
|
||||||
|
# Error Handling
|
||||||
|
|
||||||
|
Whenever you encounter an error during a task (build/test/lint/runtime/usage
|
||||||
|
issue), offer the user to save it as a rule for future sessions.
|
||||||
|
|
||||||
|
## Workflow
|
||||||
|
1. When an error occurs, briefly explain the cause and the fix.
|
||||||
|
2. Ask the user: *"Would you like to save this as a rule for future
|
||||||
|
sessions?"*
|
||||||
|
3. If yes, create a new file under `.claude/rules/` with a descriptive
|
||||||
|
filename:
|
||||||
|
```
|
||||||
|
.claude/rules/<short-topic>.md
|
||||||
|
```
|
||||||
|
4. The rule file should contain:
|
||||||
|
- A short title (the rule itself).
|
||||||
|
- The context / when it applies.
|
||||||
|
- The reason (what went wrong, why).
|
||||||
|
- The corrective action / how to avoid it.
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
Build up a project-specific knowledge base so that recurring errors and
|
||||||
|
their resolutions become permanent guidance.
|
||||||
|
|
@ -0,0 +1,25 @@
|
||||||
|
# File Path Handling
|
||||||
|
|
||||||
|
Whenever handling file paths, wrap them in quotes to safely handle spaces and
|
||||||
|
special characters.
|
||||||
|
|
||||||
|
## Examples (using a generic placeholder path)
|
||||||
|
|
||||||
|
- Quote when used in shell commands:
|
||||||
|
```bash
|
||||||
|
cd "/Users/username/Development/Project Name/"
|
||||||
|
ls "/Users/username/Development/Project Name/src"
|
||||||
|
```
|
||||||
|
|
||||||
|
- Quote inside scripts and configuration:
|
||||||
|
```bash
|
||||||
|
PROJECT_DIR="/Users/username/Development/Project Name"
|
||||||
|
cp "$PROJECT_DIR/file.txt" "$PROJECT_DIR/backup/"
|
||||||
|
```
|
||||||
|
|
||||||
|
- Quote in documentation, examples, and prompts.
|
||||||
|
|
||||||
|
## Rule
|
||||||
|
- Never use unquoted paths in shell commands or configuration files.
|
||||||
|
- Use the generic placeholder `/Users/username/Development/Project Name/`
|
||||||
|
(or similar) in documentation — never the current user's actual home path.
|
||||||
|
|
@ -0,0 +1,14 @@
|
||||||
|
# Markdown Rules
|
||||||
|
|
||||||
|
Whenever writing `.md` files, obey the basic Markdown syntax as defined by:
|
||||||
|
https://www.markdownguide.org/basic-syntax/
|
||||||
|
|
||||||
|
## Key Conventions
|
||||||
|
- Use `#`, `##`, `###` for headings (ATX-style), with a single space after the hash(es).
|
||||||
|
- Use `-` for unordered list items; `1.` for ordered lists.
|
||||||
|
- Wrap inline code in single backticks; fenced code blocks use triple backticks with a language identifier.
|
||||||
|
- Use `[text](url)` for links and `` for images.
|
||||||
|
- Bold: `**text**`. Italic: `*text*`. Strikethrough: `~~text~~`.
|
||||||
|
- Use blank lines between block elements (paragraphs, headings, code blocks, lists).
|
||||||
|
- Keep line lengths reasonable; do not insert hard wraps inside paragraphs unless required by the linter.
|
||||||
|
- Always end files with a single trailing newline.
|
||||||
|
|
@ -0,0 +1,23 @@
|
||||||
|
{
|
||||||
|
"permissions": {
|
||||||
|
"allow": [
|
||||||
|
"Bash(cd:*)",
|
||||||
|
"Bash(ls:*)",
|
||||||
|
"Bash(find:*)",
|
||||||
|
"Bash(cat:*)",
|
||||||
|
"Bash(mkdir:*)"
|
||||||
|
],
|
||||||
|
"deny": [
|
||||||
|
"Read(*/.env*)",
|
||||||
|
"Read(*/secrets/*)",
|
||||||
|
"Write(*/.env*)",
|
||||||
|
"Write(*/secrets/*)",
|
||||||
|
"Edit(*/.env*)",
|
||||||
|
"Edit(*/secrets/*)",
|
||||||
|
"Bash(rm -f*)",
|
||||||
|
"Bash(rm -rf*)",
|
||||||
|
"Bash(git push -f*)",
|
||||||
|
"Bash(git push --force*)"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -43,7 +43,11 @@ htmlcov/
|
||||||
|
|
||||||
# Cursor
|
# Cursor
|
||||||
.cursor/
|
.cursor/
|
||||||
.claude/
|
|
||||||
|
# Claude Code — track project config, ignore user-local overrides
|
||||||
|
.claude/settings.local.json
|
||||||
|
.claude/.credentials.json
|
||||||
|
.codegraph/
|
||||||
|
|
||||||
# 文档与测试程序
|
# 文档与测试程序
|
||||||
mydoc/
|
mydoc/
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue