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>
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:
- What is this project? Two sentences max.
- How do I run it? Build, test, lint commands as bash blocks.
- Architecture in one paragraph. Where the entry points are and how data flows. No diagrams unless they save words.
- Conventions specific to this repo. Naming, layout, patterns that aren't obvious from the code.
- 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,Greptools 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/Writeoutside the working tree Bashwith 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
--continueto resume a session from yesterday on a new topic. The stale context will leak in.