From 7f9ca07903a48e7c5b1123fcdf25673ab23474cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=98=BF=E7=99=BD=E5=8F=94?= <11794527+absfan@user.noreply.gitee.com> Date: Wed, 20 May 2026 09:02:21 +0800 Subject: [PATCH] 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 --- .gitignore | 33 ++++++ CLAUDE.md | 46 +++++++++ README.md | 53 ++++++++++ docs/01-vibe-coding.md | 84 +++++++++++++++ docs/02-claude-code.md | 129 ++++++++++++++++++++++++ docs/03-git-workflow.md | 90 +++++++++++++++++ docs/04-skills-and-planning.md | 112 ++++++++++++++++++++ docs/05-code-style.md | 111 ++++++++++++++++++++ docs/06-handoff.md | 121 ++++++++++++++++++++++ templates/CLAUDE.md.template | 53 ++++++++++ templates/HANDOFF_CHECKLIST.template.md | 71 +++++++++++++ templates/PR_DESCRIPTION.template.md | 52 ++++++++++ templates/README.md.template | 62 ++++++++++++ 13 files changed, 1017 insertions(+) create mode 100644 .gitignore create mode 100644 CLAUDE.md create mode 100644 README.md create mode 100644 docs/01-vibe-coding.md create mode 100644 docs/02-claude-code.md create mode 100644 docs/03-git-workflow.md create mode 100644 docs/04-skills-and-planning.md create mode 100644 docs/05-code-style.md create mode 100644 docs/06-handoff.md create mode 100644 templates/CLAUDE.md.template create mode 100644 templates/HANDOFF_CHECKLIST.template.md create mode 100644 templates/PR_DESCRIPTION.template.md create mode 100644 templates/README.md.template diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..fc36630 --- /dev/null +++ b/.gitignore @@ -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/ diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..01fd08b --- /dev/null +++ b/CLAUDE.md @@ -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: `: ` β€” e.g. `git-workflow: clarify branch naming`. +- One topic per commit. If a commit message has "and" in it, it's two commits. diff --git a/README.md b/README.md new file mode 100644 index 0000000..95e3030 --- /dev/null +++ b/README.md @@ -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. diff --git a/docs/01-vibe-coding.md b/docs/01-vibe-coding.md new file mode 100644 index 0000000..5bf86ba --- /dev/null +++ b/docs/01-vibe-coding.md @@ -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. diff --git a/docs/02-claude-code.md b/docs/02-claude-code.md new file mode 100644 index 0000000..018ce1b --- /dev/null +++ b/docs/02-claude-code.md @@ -0,0 +1,129 @@ +# 02 β€” Claude Code + +How we configure and use Claude Code across projects. + +## Configuration files + +Each project should have: + +``` +/ +β”œβ”€β”€ 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** (`/.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. diff --git a/docs/03-git-workflow.md b/docs/03-git-workflow.md new file mode 100644 index 0000000..6b3462e --- /dev/null +++ b/docs/03-git-workflow.md @@ -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: `/` β€” e.g. `bai/auth-retry`, + `bai/eval-agent-rerun`. Lowercase, hyphens, your handle as prefix. +- Long-lived integration branches: `integration/` β€” only with + team agreement. +- Delete branches after merge. Old branches confuse search. + +## Commits + +Format: + +``` +: + + +``` + +- `` 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 ". +- 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. diff --git a/docs/04-skills-and-planning.md b/docs/04-skills-and-planning.md new file mode 100644 index 0000000..df50630 --- /dev/null +++ b/docs/04-skills-and-planning.md @@ -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** (`/.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. diff --git a/docs/05-code-style.md b/docs/05-code-style.md new file mode 100644 index 0000000..ed1d199 --- /dev/null +++ b/docs/05-code-style.md @@ -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: `-v.` or `-.`. + 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. diff --git a/docs/06-handoff.md b/docs/06-handoff.md new file mode 100644 index 0000000..d2f7a16 --- /dev/null +++ b/docs/06-handoff.md @@ -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: + +``` +/ +β”œβ”€β”€ 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": "", + "source_repo": "", + "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. diff --git a/templates/CLAUDE.md.template b/templates/CLAUDE.md.template new file mode 100644 index 0000000..3246485 --- /dev/null +++ b/templates/CLAUDE.md.template @@ -0,0 +1,53 @@ +# CLAUDE.md β€” + + + +## What this project is + + + +## Run it + +```bash +# install + + +# run + + +# test + + +# lint / typecheck + +``` + +## Architecture + + + +Key files: + +- `` β€” +- `` β€” + +## Conventions specific to this repo + + + +## Don'ts + + + +- Don't <…> +- Don't <…> + +## External resources + + diff --git a/templates/HANDOFF_CHECKLIST.template.md b/templates/HANDOFF_CHECKLIST.template.md new file mode 100644 index 0000000..7e7b166 --- /dev/null +++ b/templates/HANDOFF_CHECKLIST.template.md @@ -0,0 +1,71 @@ +# Handoff checklist β€” + + + +## Identity + +- **Name**: +- **Version**: +- **Generated at**: +- **Source repo**: +- **Source commit**: +- **Author / handoff owner**: +- **Recipient**: + +## 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: `` + +## 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: +- Human-in-the-loop steps: +- Notable AI-assisted decisions: + +## Known limitations + + + +- <…> +- <…> + +## Recipient instructions + +- [ ] Read `README.md` first +- [ ] Run the verification report β€” if it fails, stop and contact the + sender +- [ ] Confirm receipt within +- [ ] Report any surprises (missing files, version mismatch, naming) + back to the sender within diff --git a/templates/PR_DESCRIPTION.template.md b/templates/PR_DESCRIPTION.template.md new file mode 100644 index 0000000..10a6803 --- /dev/null +++ b/templates/PR_DESCRIPTION.template.md @@ -0,0 +1,52 @@ + + +## Summary + + + +- +- + +## Why + + + +## What changed + + + +- `` β€” +- `` β€” + +## Test plan + + + +- [ ] Unit tests pass locally (``) +- [ ] Lint / typecheck pass (``) +- [ ] +- [ ] + +## Out of scope + + + +## Notes for reviewer + + + +--- + +πŸ€– AI-assisted with Claude Code. diff --git a/templates/README.md.template b/templates/README.md.template new file mode 100644 index 0000000..b0f2f9f --- /dev/null +++ b/templates/README.md.template @@ -0,0 +1,62 @@ +# + + + +## What it does + + + +## Quick start + +```bash +# clone +git clone +cd + +# install + + +# run + +``` + +Expected output: + +``` + +``` + +## Development + +```bash +# tests + + +# lint / typecheck + + +# format + +``` + +Code lives in ``. Tests live in ``. See [docs/](docs/) for +deeper architecture notes (or delete this line if there are none). + +## Configuration + + + +## Data sources / outputs + + + +## Related + +- +- + +## License + +