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>
130 lines
4.4 KiB
Markdown
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.
|