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

4.4 KiB

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.