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>
112 lines
4.1 KiB
Markdown
112 lines
4.1 KiB
Markdown
# 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`, not `config`. `runTask`,
|
|
not `taskRunner`.
|
|
- **Variables** — say what they are, not their type. `users`, not
|
|
`userArray`. `retryCount`, not `n`.
|
|
- **Booleans** — `is*`, `has*`, `should*`. `isReady`, not `ready`.
|
|
- **Constants** — `UPPER_SNAKE_CASE` only when truly module-level
|
|
constants. Inside functions, just use a normal `const`.
|
|
- **No abbreviations** unless they're a domain term. `database`, not
|
|
`db`. `request`, not `req`. (`req`/`res` in 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 counter` next to `counter++`
|
|
- `// 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/except` to 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:
|
|
|
|
1. **What is this?** One paragraph.
|
|
2. **How do I run it?** Bash blocks for setup, run, test.
|
|
3. **How do I develop on it?** Where the code lives, what the conventions
|
|
are.
|
|
4. **Where does the data come from / go to?** Only if non-obvious.
|
|
5. **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:
|
|
|
|
1. Versioned filename: `<name>-v<n>.<ext>` or `<name>-<YYYYMMDD>.<ext>`.
|
|
Pick one convention per project and stick to it.
|
|
2. Ships with a `README` describing schema, generation date, known
|
|
limitations.
|
|
3. Ships with a verification report (counts, checksums, sanity checks)
|
|
in the same archive.
|
|
4. 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.
|