Files
praxis/docs/02-claude-code.md
T
阿白叔andClaude Opus 4.7 7f9ca07903 init: scaffold team-guide v0.1
Working agreements for our 1-3 person AI-assisted team. Six docs
(vibe coding, Claude Code, git workflow, skills/planning, code style,
handoff) plus four templates (CLAUDE.md, README, PR description,
handoff checklist).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 09:02:21 +08:00

130 lines
4.4 KiB
Markdown

# 02 — Claude Code
How we configure and use Claude Code across projects.
## Configuration files
Each project should have:
```
<repo>/
├── CLAUDE.md ← project context (committed)
└── .claude/
├── settings.json ← shared settings (committed)
├── settings.local.json ← personal overrides (gitignored)
└── skills/ ← project-local skills (committed)
```
`settings.local.json` is **always** gitignored. Personal API keys, local
paths, and individual hook tweaks live there.
## CLAUDE.md content
Every `CLAUDE.md` answers, in this order:
1. **What is this project?** Two sentences max.
2. **How do I run it?** Build, test, lint commands as bash blocks.
3. **Architecture in one paragraph.** Where the entry points are and
how data flows. No diagrams unless they save words.
4. **Conventions specific to this repo.** Naming, layout, patterns
that aren't obvious from the code.
5. **Don'ts.** Things Claude has gotten wrong before. One line each.
A new contributor (human or AI) should be productive after reading it
once. If a `CLAUDE.md` is over 100 lines, it's drifted into documentation
and should be split.
Use `templates/CLAUDE.md.template` as the starting point.
## Permissions
Default permission posture: **prompt for everything risky, allow read-only
freely.**
In `.claude/settings.json`, allow these without prompting:
- All `Read`, `Glob`, `Grep` tools
- `Bash(git status)`, `Bash(git diff)`, `Bash(git log)`, `Bash(git branch)`
- Project-specific read-only commands (e.g. `Bash(npm test)`, `Bash(pytest)`)
Always prompt for:
- File `Edit` / `Write` outside the working tree
- `Bash` with destructive verbs (`rm`, `mv`, `git push`, `git reset --hard`, package installs)
- Any MCP tool that talks to a remote service
When you find yourself approving the same prompt over and over, run the
`fewer-permission-prompts` skill — it scans your transcripts and
proposes an allowlist.
## Hooks
Hooks are how the harness enforces rules automatically — Claude itself
won't reliably remember a "from now on…" instruction across sessions.
Use hooks for:
- Auto-formatting on file edit (Prettier, ruff, gofmt)
- Blocking edits to protected paths (`.env`, generated files, `dist/`)
- Auto-running tests after a write to a known test path
- Notifying on session stop / long-running task completion
Don't use hooks for:
- One-off checks ("just remember to do X this week")
- Anything that depends on Claude's judgment ("only run if it makes sense")
Configure via the `update-config` skill or edit `.claude/settings.json`
directly. Document each hook with a one-line comment in the JSON.
## Memory
The harness has a per-machine memory system. Use it for:
- **User**: who you are, your role, your preferences.
- **Feedback**: corrections you've given Claude that should stick across
sessions (with the *why*).
- **Project**: facts about ongoing work that aren't in the code (deadlines,
stakeholder decisions, why a refactor is happening).
- **Reference**: pointers to external resources (Linear projects, Grafana
dashboards, internal wikis).
Don't put memory content in `CLAUDE.md`. CLAUDE.md is project context,
shared with the team. Memory is personal, per-machine, and lives outside
the repo.
Don't use memory as a notes app. If it's task-scoped, it goes in a plan or
PR description.
## Skills
Skills live in three places:
- **User skills** (`~/.claude/skills/`) — installed once, available everywhere
- **Project skills** (`<repo>/.claude/skills/`) — committed, shared with team
- **Plugin skills** — installed via marketplace
Promote a workflow to a skill once you've done it the same way three
times. See `docs/04-skills-and-planning.md` for the catalog.
## Sub-agents
Spawn a sub-agent (via the `Agent` tool) when:
- The task needs a search across many files and you don't want the
results in your main context.
- You want a second, independent read on a design or diff.
- The work is genuinely parallel (e.g. researching three options).
Don't spawn sub-agents for tasks the main agent can do in two tool calls.
The handoff overhead isn't free.
## Sessions
- One task per session. Open a new session for a new task.
- If a session is running long and the context bar is filling, finish
the current step, summarize state into a plan or PR draft, then start
fresh.
- Don't use `--continue` to resume a session from yesterday on a new
topic. The stale context will leak in.