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.1 KiB
4.1 KiB
05 — Code & deliverable style
Naming, comments, structure. Same rules apply whether a human or Claude typed the code.
Naming
- Files — lowercase, hyphens for docs (
git-workflow.md), underscores for Python (task_runner.py), kebab for JS/TS where the ecosystem prefers it. Match the surrounding project. - Functions — verb phrases.
loadConfig, notconfig.runTask, nottaskRunner. - Variables — say what they are, not their type.
users, notuserArray.retryCount, notn. - Booleans —
is*,has*,should*.isReady, notready. - Constants —
UPPER_SNAKE_CASEonly when truly module-level constants. Inside functions, just use a normalconst. - No abbreviations unless they're a domain term.
database, notdb.request, notreq. (req/resin Express handlers is fine — domain convention.)
Comments
Default to none. A comment is justified when all are true:
- The why is non-obvious from the code.
- A future reader would otherwise misread the code.
- The code itself can't be made clearer (rename, extract, restructure).
Don't write:
// increment counternext tocounter++// added for the auth refactor— belongs in the commit message- Block comments restating function signatures
- TODOs without an owner or a date — they rot. Either fix it now, file an issue, or delete the comment.
Do write:
- One-liners explaining a non-obvious workaround, with the why.
- A
# NOTE:when behavior would surprise a reader. - Module headers only when a file does something the directory layout doesn't already explain.
File structure
- One concept per file. If you can't summarize the file in one sentence, split it.
- Keep tests next to the code, not in a parallel tree, unless the project already does the parallel tree.
- Generated files go in
dist/,build/, or similar — and into.gitignore. Never edit a generated file. - Lockfiles are checked in. Always.
Errors
- Fail loudly at boundaries (user input, external APIs, file I/O).
- Don't
try/exceptto silence errors. If you catch, you handle. - Internal functions trust their callers. Don't validate the same input three layers deep.
- Logged errors include enough context to debug from logs alone — what was being attempted, which inputs, which path.
Tests
- Test the behavior, not the implementation. If a refactor that preserves behavior breaks a test, the test was wrong.
- One assertion per test, ideally. "Tests that test many things at once fail unhelpfully."
- Fixtures live next to the tests that use them.
- Slow / flaky tests get marked or quarantined, not silently retried.
- New code without a test is incomplete unless the project genuinely has no test infrastructure (rare, and a bug in itself).
READMEs
Every repo has a README.md. It answers, in order:
- What is this? One paragraph.
- How do I run it? Bash blocks for setup, run, test.
- How do I develop on it? Where the code lives, what the conventions are.
- Where does the data come from / go to? Only if non-obvious.
- Pointers. Related repos, dashboards, docs.
Use templates/README.md.template. If the README is shorter than the
template, that's fine — delete the unused sections.
Deliverables (task packages, datasets, exports)
When we ship a deliverable to a partner or downstream consumer:
- Versioned filename:
<name>-v<n>.<ext>or<name>-<YYYYMMDD>.<ext>. Pick one convention per project and stick to it. - Ships with a
READMEdescribing schema, generation date, known limitations. - Ships with a verification report (counts, checksums, sanity checks) in the same archive.
- Exact commit hash that produced it goes in the README.
See docs/06-handoff.md for the full checklist.
What NOT to do
- Don't introduce a third way to do something we already do two ways. Pick one and migrate.
- Don't add config options "for flexibility" without a real use case. YAGNI.
- Don't refactor unrelated code in a feature PR. Open a separate PR.
- Don't optimize before measuring. "It might be slow" is not a measurement.