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>
This commit is contained in:
阿白叔andClaude Opus 4.7 committed 2026-05-20 09:02:21 +08:00
commit 7f9ca07903
13 files changed
+1017

No files matched your search

+33
View File
@@ -0,0 +1,33 @@
# OS
.DS_Store
Thumbs.db
desktop.ini
# Editors / IDEs
.vscode/
.idea/
*.swp
*~
# Claude Code local state
.claude/settings.local.json
.claude/projects/
.claude/sessions/
# Python
__pycache__/
*.py[cod]
.venv/
venv/
.env
.env.local
# Node
node_modules/
npm-debug.log*
yarn-error.log
# Logs / temp
*.log
tmp/
.cache/
+46
View File
@@ -0,0 +1,46 @@
# CLAUDE.md — team-guide
This repo holds our team's working agreements. When editing it, behave like
a careful technical writer, not a coder.
## Context
- **Audience**: 1–3 person team, AI-assisted development ("vibe coding").
- **Language**: English. All docs, all commits, all PR titles.
- **Tone**: short, declarative, opinionated. No fluff, no hedging, no marketing voice.
## Editing rules
- One rule per bullet. If a rule needs a paragraph of justification, split
the rule out and put the justification in a *Why* line.
- Lead with the rule, then `**Why:**`, then `**How to apply:**` only when
the rule is non-obvious. Skip them when the rule speaks for itself.
- No emoji. No decorative headers. No "🚀 Getting started!" energy.
- Keep each doc under ~150 lines. If it's growing past that, the doc is
probably two docs.
- Examples beat prose. Prefer a 3-line code block over a paragraph
describing the code.
## What goes where
| If you're writing about… | Put it in… |
| ---------------------------------------- | -------------------------------- |
| How humans and AI split a task | `docs/01-vibe-coding.md` |
| Claude Code config (CLAUDE.md, hooks…) | `docs/02-claude-code.md` |
| Branches, commits, PRs | `docs/03-git-workflow.md` |
| Which skills to install, planning cadence| `docs/04-skills-and-planning.md` |
| Naming, comments, file structure | `docs/05-code-style.md` |
| Task packages, handoff between members | `docs/06-handoff.md` |
## What NOT to do
- Don't add a doc for a rule we've used once. Wait until it's bitten us
twice — then write it.
- Don't write process for processes' sake. If nobody would read or follow
it, don't write it.
- Don't quote external sources at length (license/copyright). Link instead.
## Commits
- Commit message: `<area>: <imperative summary>` — e.g. `git-workflow: clarify branch naming`.
- One topic per commit. If a commit message has "and" in it, it's two commits.
+53
View File
@@ -0,0 +1,53 @@
# team-guide
Working agreements for our team's AI-assisted ("vibe coding") development.
Small team, English docs, opinionated but light.
## What this repo is
A single source of truth for **how we work**, not what we build. It covers:
- How we use Claude Code (CLAUDE.md, permissions, hooks, memory, skills)
- How we collaborate with AI when writing code (vibe coding norms)
- Git workflow (branches, commits, PRs, review)
- Skill management and project planning rhythm
- Code & deliverable style (naming, comments, READMEs, task packages, handoffs)
Every doc is short. If a rule needs more than half a page to justify, it
probably isn't a rule yet — it's a discussion.
## Layout
```
team-guide/
├── README.md ← you are here
├── CLAUDE.md ← context Claude Code loads when working in this repo
├── docs/
│ ├── 01-vibe-coding.md ← how humans + AI split the work
│ ├── 02-claude-code.md ← CLAUDE.md / permissions / hooks / memory / skills
│ ├── 03-git-workflow.md ← branches, commits, PRs, review
│ ├── 04-skills-and-planning.md ← skill catalog + planning cadence
│ ├── 05-code-style.md ← naming, comments, structure
│ └── 06-handoff.md ← task packages, handoff checklists
└── templates/
├── CLAUDE.md.template
├── README.md.template
├── PR_DESCRIPTION.template.md
└── HANDOFF_CHECKLIST.template.md
```
## How to use it
1. **New team member** — read `docs/01-vibe-coding.md` and `docs/03-git-workflow.md` first. The rest is reference.
2. **Starting a new project** — copy the templates from `templates/` into the new repo and fill them in. Drop a top-level `CLAUDE.md` that points back here.
3. **Disagreeing with a rule** — open a PR against this repo. Don't silently diverge.
## Versioning
This repo is versioned, not pinned. Read the latest `main`. Notable changes
get a `CHANGELOG` entry once we have one; until then, `git log` is the
changelog.
## License
Internal.
+84
View File
@@ -0,0 +1,84 @@
# 01 — Vibe coding
How humans and AI split the work on this team.
## The premise
Claude Code writes most of the code. Humans steer: framing problems,
making decisions, deciding what's good enough to ship. We're not racing
the AI — we're using it to skip typing so we can spend more time
thinking.
## The split
**Claude does:**
- Read code and explain it
- Write first-pass implementations against a clear spec
- Refactor mechanically (renames, extractions, type changes)
- Run tests, builds, linters; iterate on errors
- Generate boilerplate (configs, fixtures, templates, CRUD)
- Search across the workspace and summarize findings
**Humans do:**
- Decide what to build and why
- Frame the spec before Claude touches code
- Approve any change with non-local consequences (deps, schema, infra, auth, secrets)
- Read every diff before merging
- Make the call when Claude has tried twice and is going in circles
- Write the commit message and PR description (Claude drafts; you sign off)
If a task feels like it's drifting toward "Claude decides", stop and
write a short spec yourself first.
## Prompt habits
- **Frame, don't dictate.** Tell Claude the goal, the constraints, and
what you've already ruled out. Don't prescribe steps unless the steps
are the point.
- **Name the file.** "Fix the bug in `eval-agent/runner.py`" is better
than "fix the bug." Save Claude a search.
- **Say what done looks like.** "Tests pass and the new flag defaults to
off" — measurable. "Make it cleaner" — not.
- **One task per turn.** If you have three unrelated asks, send three
messages or open three sessions. Mixed contexts produce mixed results.
- **Push back on bad output.** If the diff is wrong, say so plainly and
point at the part that's wrong. Don't accept code you wouldn't write
yourself.
## When to stop and take over
Stop letting Claude drive when:
- It's failed the same approach twice and the error is unchanged.
- It's adding code "for safety" that the task didn't ask for.
- The diff has grown past what you can read in one sitting.
- You can't explain the change to a teammate without re-reading the diff.
- It's about to do something irreversible (delete data, force-push,
change auth) — confirm explicitly.
If you stop and take over, write down *why* in the PR description so
the next person doesn't repeat the loop.
## Verifying AI output
Treat every Claude diff like a PR from a fast junior:
1. Does it build?
2. Do the tests pass — and do new tests actually test the new code?
3. Did it touch files outside the stated scope? Look at every one.
4. Did it add deps? Check the lockfile diff.
5. Read every comment Claude added. Half of them are noise — delete those.
6. Run the feature end-to-end if it's user-facing. Type checks ≠ working software.
## Anti-patterns
- **Snowballing context.** Long sessions accumulate stale assumptions.
Start a new session for a new task.
- **Approval-by-default.** "Looks good" without reading the diff is how
bugs ship. Read it.
- **Outsourcing the spec.** "Figure out what we should do" is not a
prompt — it's avoidance.
- **Letting AI rewrite history.** If Claude wants to refactor unrelated
code "while we're here", say no. Open a separate task.
+129
View File
@@ -0,0 +1,129 @@
# 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.
+90
View File
@@ -0,0 +1,90 @@
# 03 — Git workflow
Small team, light process. Branches, commits, PRs, review.
## Branches
- `main` is always shippable. No direct pushes. No exceptions.
- Feature branches: `<owner>/<short-slug>` — e.g. `bai/auth-retry`,
`bai/eval-agent-rerun`. Lowercase, hyphens, your handle as prefix.
- Long-lived integration branches: `integration/<topic>` — only with
team agreement.
- Delete branches after merge. Old branches confuse search.
## Commits
Format:
```
<area>: <imperative summary under 60 chars>
<optional body — what changed and why, not how>
```
- `<area>` is a directory or component, lowercase: `eval-agent`,
`task_assistant`, `docs`, `git-workflow`.
- Imperative: "add", "fix", "rename" — not "added" / "adding".
- Body wraps at ~72 chars. Skip it for trivial commits.
- One topic per commit. "and" in the summary means split it.
- AI-assisted commits get the `Co-Authored-By` trailer Claude Code adds
by default. Don't strip it.
Examples:
```
eval-agent: rerun failed tasks with stable seed
docs: clarify branch naming in git-workflow
task_assistant: drop unused legacy export path
```
## Pull requests
- One PR per topic. If you can't describe it in one sentence, it's
multiple PRs.
- Title under 70 chars, same shape as a commit summary.
- Description uses `templates/PR_DESCRIPTION.template.md`.
- Push to your feature branch with `-u` the first time so it tracks
remote.
- Open the PR as soon as you have something runnable, even if it's a
draft. Review-as-you-go beats review-at-the-end.
## Review
We review every PR before merge, even our own AI-assisted ones.
Reviewer checks:
1. Does the description match the diff? If the diff has surprises, ask.
2. Read every file changed. If a file isn't related to the stated
topic, ask why it's in the PR.
3. Run the change locally if it's not obviously correct from reading.
4. New deps, schema changes, env vars, or auth-touching code → block
until justified.
5. Comment on the *least* important issue first; save the merge-blocker
for last so it's clearly the gate.
Author follow-ups:
- Address every comment, even with "agreed, fixed in <commit>".
- If you disagree, push back in writing. Don't silently ignore.
- Squash fixup commits before merge if the history is noisy.
## Merging
- Squash for feature branches. Merge commits are reserved for
integration branches.
- Final squash message follows the commit format above. The PR title is
usually the right starting point.
- Delete the branch on merge.
## What NOT to do
- No `git push --force` to `main`. Period. To your own branch, only if
nobody else has pulled it.
- No `--no-verify` to skip hooks. Fix what the hook is complaining
about.
- No amending pushed commits. Once it's on the remote, add a new commit.
- No committing `.env`, credentials, or files larger than ~5 MB without
a Git LFS conversation first.
- No staging with `git add .` or `git add -A` when there are untracked
files you don't recognize. Stage by name.
+112
View File
@@ -0,0 +1,112 @@
# 04 — Skills and planning
How we manage the skill catalog and how we plan work as a small team.
## Skill catalog
A "skill" is a reusable, named workflow Claude Code can invoke. We keep
three catalogs:
- **Personal** (`~/.claude/skills/`) — private, per developer.
- **Team** (`<repo>/.claude/skills/`) — committed, shared via the project.
- **Bundled / plugin** — installed from a marketplace.
### When to make a skill
Promote a workflow to a skill when **all three** are true:
1. You've done it the same way three times.
2. The steps are stable enough to write down.
3. Someone else on the team would do it the same way if shown.
If only two are true, leave it as a prompt snippet in your notes.
### Skill design rules
- One skill, one job. Skills that branch on "what does the user want?"
are two skills.
- Name the skill as a verb phrase: `review-pr`, `cut-release`,
`rebuild-fixtures`. Not `pr-helper`.
- Description (the one-liner the model sees) must say *when to invoke*,
not what the skill does. The model decides on the *when*.
- Keep `SKILL.md` under 200 lines. Long skills get broken into stages.
- Examples beat instructions. Show one good run.
### Reviewing skills
Treat a new skill like a PR: read it, run it once on a real task, then
merge. Skills that nobody runs after a month get archived (move to
`.claude/skills/_archive/`).
### Active skills (this team)
Maintain this list as we go. Drop a one-line description and the path.
```
# Personal recommendations (install with marketplace or copy):
# anthropic-skills:consolidate-memory — periodic memory cleanup
# simplify — review changed code for reuse/quality
# fewer-permission-prompts — propose allowlist from transcripts
# review — review a pull request
# security-review — security pass on pending changes
# Team skills (in this repo):
# (none yet — add as we promote workflows)
```
## Planning cadence
We're 1–3 people. Process should be the lightest thing that keeps us
aligned. Right now that's:
### Weekly
- One short async written sync (Mon morning). Each person posts:
1. What I shipped last week (one line per item).
2. What I'm picking up this week (one line per item).
3. What's blocked or unclear (the only section worth reading carefully).
- 30-minute live call mid-week. Agenda comes from the "blocked or
unclear" lines.
### Per-task
Before starting work that will take more than ~half a day:
1. Write a 5-line spec: *Goal / Why / Done when / Out of scope / Risks*.
2. Drop it in the PR description (draft PR is fine) **before** writing
code.
3. If Claude is going to do most of the typing, the spec is also the
prompt — paste it in.
After finishing:
1. PR description updated to match what actually shipped.
2. Anything you learned that future-you would want goes into Claude
memory (feedback / project type) — see `docs/02-claude-code.md`.
### Per-quarter
One half-day to:
- Re-read this `team-guide` repo. Open PRs for what's stale.
- Review the skill catalog. Archive what we don't use.
- Run `consolidate-memory` against personal memory files.
## Project structure
When starting a new project under this workspace:
1. Copy `templates/README.md.template` and `templates/CLAUDE.md.template`.
2. `git init` immediately, even if the project is throwaway. Throwaway
projects survive longer than you expect.
3. First commit: scaffolding only, no real code. Makes future `git log`
readable.
4. Add the project to the workspace `README` (when we have one) so it's
discoverable.
## What planning is *not*
- It's not Jira tickets. We don't need a board for two people.
- It's not Gantt charts. If we need one, we're building the wrong thing.
- It's not status theater. The Monday post is for spotting blocks, not
for proving you worked.
+111
View File
@@ -0,0 +1,111 @@
# 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.
+121
View File
@@ -0,0 +1,121 @@
# 06 — Handoff
Task packages, deliverables, and how we hand work between team members
or to external consumers.
## Why this matters
Handoff failures cost more than the original work. A package that's
"obviously how it works" to the author is a half-day of confusion for
the recipient. Treat handoff as part of the deliverable, not as
afterthought packaging.
## Two kinds of handoff
1. **Internal** — passing work to another team member (or future-you).
Usually a branch, a PR, or a half-finished prototype.
2. **External** — shipping a versioned artifact to a partner, customer,
or downstream pipeline. Usually a zip, a dataset, or a release.
Both use the checklist in `templates/HANDOFF_CHECKLIST.template.md`. The
external case has a higher bar.
## Task packages
When we ship a task package (e.g. `praxis-sample-5.zip`,
`task-assistant-v0.2-handoff-*.zip`), it must contain:
```
<package>/
├── README.md ← what this is, who it's for, how to use it
├── CHANGELOG.md ← what changed since the last version
├── VERIFICATION.md ← counts, checksums, sanity checks
├── manifest.json ← machine-readable metadata
├── data/ ← the actual deliverable
└── scripts/ ← only what's needed to use the package
```
`manifest.json` minimum fields:
```json
{
"name": "praxis-sample-5",
"version": "0.5.0",
"generated_at": "2026-05-18T17:00:00Z",
"source_commit": "<full sha>",
"source_repo": "<git remote url>",
"record_count": 1234,
"schema_version": "1.0"
}
```
If you can't fill a field, leave it as `null` and explain in the README.
Never make one up.
## Internal handoff (branch / PR)
Before handing off:
- PR description is current. The summary describes what shipped, not
what was attempted.
- The "test plan" section in the PR template is filled in honestly. If
you didn't test something, say so — don't bury it.
- Any AI-assisted decisions that surprised you go in a `## Notes for
reviewer` section. "Claude tried X first, that didn't work because Y,
here's the working approach" saves the reviewer a re-derivation.
- Local-only state (env vars, scratch data) is documented or scripted.
"Works on my machine" is not a handoff.
The recipient should be able to:
1. `git checkout` the branch
2. Read the PR description
3. Run the test plan
4. Form an opinion
— without messaging you. If they have to message you, the handoff is
incomplete.
## External handoff (versioned artifact)
Higher bar. In addition to the task package contents above:
- **Reproducibility.** Someone with access to the source repo can
rebuild the artifact from the commit hash in `manifest.json`. Test
this at least once before the first release.
- **Verification report.** A machine-checkable report (JSON or
similar) showing the artifact passed our pre-ship checks. Include
what was checked and the result.
- **Provenance.** If the artifact was generated using AI assistance,
note the model and any human-in-the-loop steps. Not for ceremony —
for debugging when something looks wrong six months from now.
- **License & attribution.** Even for internal partners. Be explicit
about what they can and can't do with the data.
## What NOT to ship
- Files larger than ~500 MB without a conversation about delivery
channel.
- Anything containing real PII unless that was explicitly the deal.
- `.env`, secrets, API keys, internal hostnames.
- "Final final v3" filenames. Use the version field. If it's `final`,
it's `v1.0`.
- A package without a README. Even a one-line README beats none.
## Receiving a handoff
When you're on the receiving end:
1. Read the README first, fully. Resist the urge to start running
scripts.
2. Run the verification report. If it doesn't pass, stop and message
the sender before doing anything else.
3. Note any surprise — naming, missing files, version mismatch — and
send it back to the sender within a day. Drift gets worse with
silence.
## Templates
- `templates/HANDOFF_CHECKLIST.template.md` — fill out per handoff,
ships in the package.
- `templates/PR_DESCRIPTION.template.md` — for internal handoff via PR.
+53
View File
@@ -0,0 +1,53 @@
# CLAUDE.md — <project name>
<!--
Template. Copy into a new repo and fill the bracketed sections.
Delete sections that don't apply. Keep total length under ~100 lines.
-->
## What this project is
<One or two sentences. What does it do, who is it for.>
## Run it
```bash
# install
<command>
# run
<command>
# test
<command>
# lint / typecheck
<command>
```
## Architecture
<One paragraph. Where are the entry points, how does data flow, what
are the major modules. Skip diagrams unless they save words.>
Key files:
- `<path>` — <one-line role>
- `<path>` — <one-line role>
## Conventions specific to this repo
<Anything that's not obvious from reading the code. Naming patterns,
where to add new features, what's auto-generated, etc.>
## Don'ts
<Things Claude or a new contributor has gotten wrong before.
One line each. Add to this list as you discover them.>
- Don't <…>
- Don't <…>
## External resources
<Links to dashboards, related repos, docs, ticket trackers.>
+71
View File
@@ -0,0 +1,71 @@
# Handoff checklist — <package or branch name>
<!--
Fill this out before declaring the handoff complete.
Ships inside the package for external handoffs.
Lives in the PR description for internal handoffs.
-->
## Identity
- **Name**: <package or branch name>
- **Version**: <e.g. v0.5.0 or commit sha>
- **Generated at**: <ISO timestamp>
- **Source repo**: <url>
- **Source commit**: <full sha>
- **Author / handoff owner**: <name>
- **Recipient**: <name or team>
## Contents
- [ ] `README.md` — describes what this is, how to use it
- [ ] `CHANGELOG.md` — what's different from the previous version (or
"first release")
- [ ] `manifest.json` — machine-readable metadata, all fields filled or
explicitly null
- [ ] `VERIFICATION.md` — what we checked, what passed
- [ ] Data / artifacts — the actual deliverable
- [ ] Scripts — only what's needed to use the package
## Verification
- [ ] Record / file counts match expected
- [ ] Checksums computed and recorded
- [ ] Sanity checks pass (list them)
- [ ] No secrets, `.env`, or credentials included
- [ ] No PII unless explicitly part of the deliverable
- [ ] Total size reasonable for delivery channel
Verification report path: `<path>`
## Reproducibility
- [ ] Confirmed someone with repo access can rebuild from
`source_commit` (note who tested this and when)
- [ ] Build / generation command documented in `README.md`
- [ ] External dependencies pinned to versions
## Provenance (if AI-assisted)
- Model used: <e.g. claude-opus-4-7>
- Human-in-the-loop steps: <which parts a human reviewed / approved>
- Notable AI-assisted decisions: <anything that would matter if the
output looks wrong six months from now>
## Known limitations
<Things that don't work, edge cases that aren't covered, follow-ups
that didn't make this version. Be specific. "Works on my machine" is
not a limitation, it's a problem to fix before shipping.>
- <…>
- <…>
## Recipient instructions
- [ ] Read `README.md` first
- [ ] Run the verification report — if it fails, stop and contact the
sender
- [ ] Confirm receipt within <X days>
- [ ] Report any surprises (missing files, version mismatch, naming)
back to the sender within <X days>
+52
View File
@@ -0,0 +1,52 @@
<!--
PR description template. Title goes in the PR title field, not here.
Title format: <area>: <imperative summary under 70 chars>
-->
## Summary
<One sentence describing what this PR does. Then 1–3 bullets if needed.>
- <bullet>
- <bullet>
## Why
<The motivation. What problem does this solve, what decision does it
implement, what bug does it fix. If this links to an issue or earlier
discussion, link it here.>
## What changed
<Bulleted list of the actual changes, grouped by area if it spans
multiple. Keep it factual — the diff is the source of truth, this is
just a map.>
- `<file or area>` — <change>
- `<file or area>` — <change>
## Test plan
<Bulleted checklist. Mark `[x]` for done, `[ ]` for didn't do (and
explain why below). Be honest — "didn't test" is acceptable, "claimed
tested but didn't" is not.>
- [ ] Unit tests pass locally (`<command>`)
- [ ] Lint / typecheck pass (`<command>`)
- [ ] <feature-specific check>
- [ ] <feature-specific check>
## Out of scope
<Things you noticed but explicitly chose not to fix in this PR. Helps
reviewers not bring them up.>
## Notes for reviewer
<Anything that surprised you, AI-assisted decisions worth flagging,
shortcuts taken, or "I considered X but went with Y because Z". Skip
this section if there's nothing notable.>
---
🤖 AI-assisted with Claude Code.
+62
View File
@@ -0,0 +1,62 @@
# <project name>
<One sentence. What this is, in plain language.>
## What it does
<One paragraph. Slightly more detail than the tagline. Who would use
it, what problem it solves, what it explicitly does not do.>
## Quick start
```bash
# clone
git clone <url>
cd <repo>
# install
<command>
# run
<command>
```
Expected output:
```
<a few lines of what the user should see>
```
## Development
```bash
# tests
<command>
# lint / typecheck
<command>
# format
<command>
```
Code lives in `<dir>`. Tests live in `<dir>`. See [docs/](docs/) for
deeper architecture notes (or delete this line if there are none).
## Configuration
<Env vars, config files, secrets. Point to a `.env.example` if there is
one. Don't list real values.>
## Data sources / outputs
<Only if non-obvious. Where does input come from, where do outputs go.>
## Related
- <link>
- <link>
## License
<Internal / MIT / etc.>