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/
|
||||
.claude/
|
||||
|
||||
# Claude Code — track project config, ignore user-local overrides
|
||||
.claude/settings.local.json
|
||||
.claude/.credentials.json
|
||||
.codegraph/
|
||||
|
||||
# 文档与测试程序
|
||||
mydoc/
|
||||
|
|
|
|||
Loading…
Reference in New Issue