3 Commits
Author SHA1 Message Date
阿白叔andClaude Opus 4.7 94eb7ef70a docs: collapse docs/ into single AGENTS.md, slim README
Single source of truth for AI is AGENTS.md. CLAUDE.md becomes a
one-line @AGENTS.md import so Claude Code and Codex read the same
spec — zero drift. README.md becomes a short Chinese entry point
(language policy, layout, tag styles, top pitfalls) and links into
AGENTS.md for full rules.

- Consolidate docs/01-08 into AGENTS.md (7 sections, ~700 lines)
- README.md: ~80-line Chinese entry point, no rule duplication
- CLAUDE.md: just "@AGENTS.md"
- Delete docs/ — content preserved in git history at tag 20260520-3

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 16:56:19 +08:00
阿白叔andClaude Opus 4.7 dfa84743f9 docs: add product project spec, distinguish date vs semver tags
Distill task_assistant's COLLABORATION_AND_RELEASE_WORKFLOW into a
team-wide product project spec and clarify when each tag style applies.

- Add docs/08-product-spec.md: semver triplet (internal/display/tag),
  manifest schema, dist-channel separation, user-confirmed update
  flow, feedback/log handling, sensitive-info scan, release flow,
  minimum delivery checklist
- docs/03-git-workflow.md: split tagging into spec (YYYYMMDD) vs
  product (vX.Y.Z) sections, link to 08
- README.md, CLAUDE.md, AGENTS.md: update versioning section and doc
  index to reference 08

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 14:45:28 +08:00
阿白叔andClaude Opus 4.7 154f592f3c docs: split language by audience, add Codex / AGENTS.md spec
Language policy: Chinese for human-facing files (README, docs/,
human-fillable templates), English for AI-facing files (CLAUDE.md,
AGENTS.md, AI templates). Commits / PRs / branches / tags stay
English.

- Translate docs/01-06 to Chinese
- Translate README.md, PR / handoff / project README templates to Chinese
- Drop README.en.md (redundant once language policy is explicit)
- Rewrite CLAUDE.md and CLAUDE.md.template under the new policy
- Add AGENTS.md (root) and templates/AGENTS.md.template for Codex
- Add docs/07-codex.md covering Codex usage and AGENTS.md / CLAUDE.md sync rules

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 09:44:15 +08:00
15 changed files with 1193 additions and 949 deletions

No files matched your search

+962
View File
@@ -0,0 +1,962 @@
# AGENTS.md — team-guide
Working agreements for our 1–3 person AI-assisted development team.
This is the canonical spec for AI coding agents (Claude Code, Codex,
and any other `AGENTS.md`-aware tool). Claude Code reads this via
`CLAUDE.md`'s `@AGENTS.md` import, so there's exactly one source of
truth.
> Human-facing entry point: [`README.md`](README.md) (Chinese,
> condensed). When humans want the full ruleset, they read this file.
## Project
This repo holds our team's working agreements. It is **documentation,
not code** — no build, test, or lint step. Acceptance is "a human can
read the change and would have written the same."
## Editing rules (this repo)
- One rule per bullet. If a rule needs a paragraph of justification,
split the rule out and put the reason on a `**Why:**` line.
- Lead with the rule, then `**Why:**`, then `**How to apply:**` only
when the rule isn't self-evident.
- No emoji. No decorative headers. No "🚀 Getting started!" energy.
- Keep AGENTS.md under ~800 lines. Past that, split.
- Examples beat prose. A 3-line code block beats a paragraph.
## Language policy
- **Human-facing**: Chinese — `README.md` and the human-fillable
templates (`templates/README.md.template`,
`templates/PR_DESCRIPTION.template.md`,
`templates/HANDOFF_CHECKLIST.template.md`).
- **AI-facing**: English — this file, `CLAUDE.md`,
`templates/CLAUDE.md.template`, `templates/AGENTS.md.template`.
- **Git metadata**: English — commit messages, PR titles, branch
names, tag annotations. AI tools and search work better on English.
If you're an agent about to write Chinese into a file the human would
never read (or English into a file only humans read), stop — wrong file.
## CLAUDE.md and AGENTS.md sync
Claude Code reads `CLAUDE.md`; Codex and other agents read `AGENTS.md`.
In this repo, `CLAUDE.md` is a single line: `@AGENTS.md`. That makes
this file the only spec; both tools see the same content.
For other projects in our workspace where the two files are physical
copies (legacy or tool-mismatch reasons), the rules are:
- Bodies must stay in sync. Drift breaks one of the tools silently.
- Whoever edits one updates the other in the same PR. Add "Synced
AGENTS.md" (or "Synced CLAUDE.md") to the PR description.
- Reviewer blocks PRs that only touch one side.
When starting a new project, prefer the single-file approach: write
`AGENTS.md`, make `CLAUDE.md` a one-line `@AGENTS.md` import.
---
## 1. Vibe coding — humans + AI work split
### The premise
Claude / Codex write most of the code. Humans steer: framing problems,
making decisions, deciding what's good enough. We're not racing the AI
— we're skipping typing so we spend more time thinking.
### The split
**AI does:**
- Read code and explain it
- Write first-pass implementations against a clear spec
- Mechanical refactors (renames, extractions, type changes)
- Run tests, builds, linters; iterate on errors
- Generate boilerplate (configs, fixtures, CRUD)
- Search across the workspace and summarize
**Humans do:**
- Decide what to build and why
- Frame the spec before AI touches code
- Approve any change with non-local consequences (deps, schema, infra,
auth, secrets)
- Read every diff before merging
- Make the call when AI has tried twice and is going in circles
- Sign off on commit messages and PR descriptions (AI drafts; you sign)
If a task feels like it's drifting toward "AI decides", stop and write
a spec yourself first.
### Prompt habits
- **Frame, don't dictate.** Tell AI the goal, the constraints, and what
you've ruled out. Don't prescribe steps unless the steps are the point.
- **Name the file.** "Fix the bug in `eval-agent/runner.py`" beats "fix
the bug." Save AI 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.** Three unrelated asks → three messages or three
sessions.
- **Push back on bad output.** If the diff is wrong, say so plainly and
point at what's wrong. Don't accept code you wouldn't write yourself.
### When to take over
Stop letting AI drive when:
- It's failed the same approach twice and the error is unchanged.
- It's adding "safety" code 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 — confirm explicitly.
When you take over, write *why* in the PR description so the next person
doesn't repeat the loop.
### Verifying AI output
Treat every AI diff like a fast junior's PR:
1. Does it build?
2. Do 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 AI added. Half are noise — delete those.
6. Run user-facing features end-to-end. Type checks ≠ working software.
### Anti-patterns
- **Snowballing context.** Long sessions accumulate stale assumptions.
New task → new session.
- **Approval-by-default.** "Looks good" without reading the diff is how
bugs ship.
- **Outsourcing the spec.** "Figure out what we should do" is avoidance,
not a prompt.
- **Letting AI rewrite history.** If AI wants to refactor unrelated code
"while we're here", say no. Open a separate task.
---
## 2. Claude Code & Codex configuration
### Per-project files
```
<repo>/
├── AGENTS.md ← canonical spec, committed
├── CLAUDE.md ← committed, single line: @AGENTS.md
└── .claude/
├── settings.json ← shared settings, committed
├── settings.local.json ← personal overrides, gitignored
└── skills/ ← project skills, committed
```
`settings.local.json` is **always** gitignored — personal API keys,
local paths, individual hook tweaks.
### AGENTS.md content per project
In this order:
1. **Project** — two sentences max.
2. **Run it** — build, test, lint as bash blocks.
3. **Architecture** — one paragraph. Entry points and data flow. 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 AI has gotten wrong before. One line each.
A new contributor (human or AI) should be productive after one read.
Past 100 lines, split — it's drifted into "documentation."
Use [`templates/AGENTS.md.template`](templates/AGENTS.md.template).
### Permissions (Claude Code)
Default: prompt for risky, allow read-only freely.
In `.claude/settings.json`, allow without prompting:
- All `Read`, `Glob`, `Grep`
- `Bash(git status)`, `Bash(git diff)`, `Bash(git log)`,
`Bash(git branch)`
- Project-specific read-only commands (`Bash(npm test)`, `Bash(pytest)`)
Always prompt for:
- `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
Approving the same prompt repeatedly → run the
`fewer-permission-prompts` skill to propose an allowlist from your
transcripts.
### Codex approval & sandbox
- **Approval**: default `on-request` (asks before commands). Use
`on-failure` or `never` only on personal, low-risk machines.
Production / shared / unfamiliar repos → keep `on-request`.
- **Sandbox**: default `workspace-write` + network off. Toggle network
on temporarily to install packages or fetch resources, then off.
`danger-full-access` rarely.
- Personal Codex preferences in `~/.codex/config.toml` — never commit.
### Hooks
Hooks enforce rules automatically. AI **does not reliably remember**
"from now on do X" across sessions; hooks do.
Use hooks for:
- Auto-formatting on file edit (Prettier, ruff, gofmt)
- Blocking edits to protected paths (`.env`, generated files, `dist/`)
- Auto-running tests after writing to a known test path
- Notifying on session stop / long-task completion
Don't use hooks for:
- One-off checks ("just remember X this week")
- Anything that depends on AI judgment
Configure via `update-config` skill or edit `.claude/settings.json`
directly. One-line comment per hook.
### Memory
Per-machine memory system. Use it for:
- **User**: who you are, role, preferences.
- **Feedback**: corrections 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, Grafana,
internal wikis).
Don't put memory content in `AGENTS.md`. AGENTS.md is shared with the
team; memory is personal, per-machine, outside the repo. Don't use
memory as a notes app — task-scoped state goes in plans or PR descriptions.
### Skills
Skills live in three places:
- **User skills** (`~/.claude/skills/`) — installed once, available
everywhere
- **Project skills** (`<repo>/.claude/skills/`) — committed, team-shared
- **Plugin skills** — installed via marketplace
Promote a workflow to a skill when **all three** are true:
1. Done it the same way three times.
2. Steps stable enough to write down.
3. Someone else would do it the same way given the spec.
Only two true → leave it as a prompt snippet.
Skill design:
- One skill, one job. Branching skills are two skills.
- Verb-phrase names: `review-pr`, `cut-release`, `rebuild-fixtures` —
not `pr-helper`.
- Description (the line the model sees) says **when to invoke**, not
what the skill does.
- `SKILL.md` under 200 lines; long skills split into stages.
- Examples beat instructions.
Recommended installs:
```
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
```
Review skills like PRs — read, run once on a real task, merge. Skills
nobody runs after a month → archive (`.claude/skills/_archive/`).
### Sub-agents
Spawn a sub-agent (Claude `Agent` tool) when:
- Task needs cross-file search and you don't want results in main context.
- You want a second independent read on a design or diff.
- Work is genuinely parallel (e.g. researching three options).
Don't spawn for tasks the main agent can do in two tool calls.
### Sessions
- One task per session. New task → new session.
- Long session, context bar filling → finish current step, summarize
into a plan or PR draft, start fresh.
- Don't `--continue` yesterday's session for a new topic. Stale context
leaks in.
### Tool selection (mixing Claude Code + Codex)
Both fine; mild preferences:
- **Writing docs / specs** — Claude Code (this repo was written that way).
- **Large refactors / cross-file features** — Claude Code (plan mode +
sub-agents).
- **Narrow edits, run a test, change a config** — Codex CLI (faster
startup).
- **In-IDE inline edits** — Codex IDE plugin or Cursor.
Don't run two tools editing the same file simultaneously — overwrites
are hard to trace.
---
## 3. Git workflow
### Branches
- `main` (spec repos) / `dev` (product repos) is always shippable. No
direct pushes, no exceptions.
- Feature branches: `<owner>/<short-slug>` — `bai/auth-retry`,
`bai/eval-agent-rerun`. Lowercase, hyphens, handle prefix.
- Long-lived integration: `integration/<topic>` — only by team agreement.
- Delete branches after merge.
### Commits
```
<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 → split.
- Always include `Co-Authored-By` for AI-assisted commits.
- English.
Examples:
```
eval-agent: rerun failed tasks with stable seed
docs: clarify branch naming
task_assistant: drop unused legacy export path
```
### Pull requests
- One PR per topic. Can't describe in one sentence → multiple PRs.
- Title under 70 chars, same shape as commit summary.
- Description uses
[`templates/PR_DESCRIPTION.template.md`](templates/PR_DESCRIPTION.template.md).
- First push of a feature branch uses `-u`.
- Open as draft once runnable. Review-as-you-go beats review-at-the-end.
### Review
Every PR reviewed before merge — own AI-assisted PRs included.
Reviewer:
1. Description matches diff? Surprises → ask.
2. Read every changed file. Off-topic file → ask why it's in this PR.
3. Run locally if not obviously correct from reading.
4. New deps, schema changes, env vars, auth-touching code → block until
justified.
5. Comment on least-important issue first; merge-blocker last so it's
clearly the gate.
Author follow-ups:
- Address every comment, even with "agreed, fixed in <commit>".
- Disagree → push back in writing. Don't silently ignore.
- Squash fixup commits before merge if history is noisy.
### Merging
- Squash for feature branches. Merge commits reserved for integration.
- Final squash message follows commit format.
- Delete the branch on merge.
### Tagging
Two styles by project type:
| Project type | Tag format | Example | Tag from |
| ------------ | ------------------ | ------------------------ | -------- |
| Spec repo | `YYYYMMDD[-N]` | `20260520`, `20260520-2` | `main` |
| Product repo | `vX.Y.Z` | `v0.2.4` | `dev` |
Decide: would a "user" receive a versioned artifact from this project?
Yes → product. No → spec.
Universal:
- Annotated only (`git tag -a`).
- Tag message summarizes what changed since the previous tag.
- Tags are immutable once pushed. Wrong tag → cut a new one.
- Don't tag on feature branches.
Spec-repo specific: max one tag per day. Same-day reissues → `-N`
suffix.
Product-repo specific: see [Product project rules](#5-product-projects)
for the full ruleset (semver triplet, manifest, sync list).
Spec tag:
```bash
git checkout main && git pull --ff-only
git tag -a 20260520 -m "team-guide 20260520: bilingual policy"
git push origin 20260520
```
Product tag:
```bash
git checkout dev && git pull --ff-only <remote> dev
git tag -a v0.2.4 HEAD -m "<Project> V0.2.4"
git push <remote> v0.2.4
```
Inspect:
```bash
git tag --sort=-creatordate
git show 20260520
git log --oneline 20260513..20260520
```
When to cut a spec-repo tag:
- Docs changed in a way teammates need to re-read.
- A template was added, removed, or restructured.
- A new convention is now in effect (not just proposed).
When **not** to cut a spec-repo tag:
- Typos, formatting, link fixes → just push to `main`.
- Drafts under discussion → use a PR.
Product tagging follows the release flow in
[Product projects](#5-product-projects).
### Don'ts
- No `git push --force` to `main`. Period. To your own branch only if
certain nobody pulled it.
- No `--no-verify` to skip hooks. Fix what the hook reports.
- No amending pushed commits. Add a new commit instead.
- No deleting or moving pushed tags. Cut a new one.
- No committing `.env`, secrets, or files >5 MB without a Git LFS
conversation.
- No `git add .` / `git add -A` when there are unrecognized untracked
files. Stage by name.
---
## 4. Code & deliverable style
### Naming
- **Files** — lowercase. Docs hyphenated (`git-workflow.md`), Python
underscored (`task_runner.py`), JS/TS kebab where ecosystem prefers.
Match the surrounding project.
- **Functions** — verb phrases. `loadConfig`, not `config`. `runTask`,
not `taskRunner`.
- **Variables** — what they are, not their type. `users`, not
`userArray`. `retryCount`, not `n`.
- **Booleans** — `is*`, `has*`, `should*`. `isReady`, not `ready`.
- **Constants** — `UPPER_SNAKE_CASE` only at module level. Inside
functions, plain `const`.
- **No abbreviations** unless they're domain terms. `database`, not
`db`. (`req`/`res` in Express is fine.)
### Comments
Default: none. Justified when **all** are true:
- *Why* is non-obvious from code.
- A future reader would otherwise misread.
- The code 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 signatures
- TODOs without owner or date
Do write:
- One-liners for non-obvious workarounds, with the *why*.
- `# NOTE:` for behavior that would surprise a reader.
- Module headers when the file does something the layout doesn't explain.
### File structure
- One concept per file. Can't summarize in one sentence → split.
- Tests next to the code unless project already uses parallel test trees.
- Generated files in `dist/`, `build/`, etc. — and `.gitignore`. Never
edit a generated file.
- Lockfiles always checked in.
### Errors
- Fail loudly at boundaries (user input, external APIs, file I/O).
- Don't `try/except` to silence. Catch → handle.
- Internal functions trust callers. Don't validate the same input three
layers deep.
- Logged errors include enough context to debug from logs alone.
### Tests
- Test behavior, not implementation. Behavior-preserving refactor that
breaks a test → test was wrong.
- One assertion per test ideally.
- Fixtures next to the tests using them.
- Slow / flaky tests get marked or quarantined, not silently retried.
- New code without a test is incomplete unless project has no test
infrastructure (rare, and a bug itself).
### READMEs
Every repo has one. In order:
1. **What is this?** One paragraph.
2. **How do I run it?** Bash blocks.
3. **How do I develop on it?** Code layout, conventions.
4. **Where does data come from / go to?** Only if non-obvious.
5. **Pointers.** Related repos, dashboards, docs.
Use [`templates/README.md.template`](templates/README.md.template).
Shorter than the template is fine — delete unused sections.
### Don'ts
- No third way to do something we already do two ways.
- No config options "for flexibility" without a real use case. YAGNI.
- No unrelated refactors in a feature PR. Open a separate one.
- No optimization before measurement.
---
## 5. Product projects
For projects that ship versioned artifacts to users (task_assistant,
authoring-tool, etc.). Spec repos (this one) ignore this section.
### Spec vs product
| Dimension | Spec repo | Product repo |
| ------------------ | ---------------------------- | ------------------------------------- |
| Content | Docs, conventions, templates | Executable code, shippable artifacts |
| Tag format | `YYYYMMDD` / `YYYYMMDD-N` | `vX.Y.Z` |
| Acceptance | Human can read it | Tests pass, runs |
| Distribution | Git itself | Git (source) + dist channel (binaries)|
| Version-field sync | None | Multiple sites must agree |
| Users | Team members | Real end users |
Unsure? "Will a user receive a versioned artifact from this?" Yes → product.
### Versioning
Semver triplet: `major.minor.patch`.
- **major** — backward-incompatible (schema, CLI args, artifact format)
- **minor** — backward-compatible additions
- **patch** — bug fixes, perf, internal refactors
Three forms, **all must agree**:
| Use | Format | Example | Where |
| ----------- | --------- | --------- | ----------------------------------- |
| Internal | `X.Y.Z` | `0.2.4` | `package.json`, `pyproject.toml` |
| Display | `VX.Y.Z` | `V0.2.4` | UI chips, README title, release note|
| Git tag | `vX.Y.Z` | `v0.2.4` | Git tag |
Each product project lists its **release-bump checklist** in one place
(usually its own `AGENTS.md`). task_assistant's example:
```
package.json "version": "0.2.4"
public/index.html version chip default
server.js fallback version
scripts/build-release.js fallback + release notes
scripts/build-release-windows.js fallback + release notes
README.md title, version status
README.en.md same
```
Miss one → next release drifts.
### Tags (product)
- Annotated. Message: `<Project Name> V<x.y.z>`.
- One version, one tag — don't split across platforms.
- Already-shipped tags don't move. Wrong → ship a patch.
- Mistake before shipping (rare):
```bash
git tag -d v0.2.4
git push <remote> :refs/tags/v0.2.4
git tag -a v0.2.4 <correct-sha> -m "<Project> V0.2.4"
git push <remote> v0.2.4
```
### Branches
`dev` is the collaboration trunk. Feature branches off `dev`, PR back to
`dev`. Don't keep an unclear `master`. Stable branches use clear names:
`release/v0.3`, `release/v0.3-hotfix`.
### Git vs distribution channel
Git holds source. The distribution channel (OpenList, Hugging Face,
S3, etc.) holds artifacts. They don't mix.
Into Git:
- Source, build scripts, docs, conventions, small static assets,
templates, role/config tables.
Out of Git:
```
config/ local config
logs/ runtime logs
feedback-records/ user feedback
generated_task_packages/ task outputs
reports/ verification reports
runtime-temp/ transient state
release/ release-build/ release-dev/ release-merge/
.venv/ __pycache__/ node_modules/
```
Distribution channel layout (typical):
```
/<project>/dist/ release zips + manifest
/<project>/feedback/<machine-id>/ uploaded user feedback
```
Release zips are **self-contained**: user unzips, clicks, runs. No
dependency installs on user machines.
### Manifest
Top-level `manifest.json` in the dist channel — clients read it to
decide whether to update:
```json
{
"name": "<project-name>",
"version": "0.2.4",
"displayVersion": "V0.2.4",
"released_at": "2026-05-18T17:00:00Z",
"platforms": {
"windows": {
"url": "<dist-url>/<project>-v0.2.4-windows.zip",
"size": 123456789,
"sha256": "<hex>"
},
"macos-arm64": { "url": "...", "size": ..., "sha256": "..." },
"macos-x64": { "url": "...", "size": ..., "sha256": "..." }
},
"release_notes": "<short markdown>"
}
```
After upload, **re-fetch** the manifest and eyeball size + sha256.
Same size as previous → cache or upload error.
### Update flow (user-confirmed, not silent)
1. Client startup fetches manifest, compares versions.
2. New version → **prompt the user**, don't auto-download.
3. User confirms → download to local.
4. User confirms install → restart.
Never silently skip a step. This goes in every product's `AGENTS.md`
"Don'ts."
### Feedback & logs
Local-first, async upload:
```
local:
feedback-records/feedback-<timestamp>-<id>.json
logs/<project>-YYYY-MM-DD.jsonl
remote (after successful upload):
/<project>/feedback/<machine-id>/<feedback-file>.json
```
- Upload failure must not lose local data. UI says "saved locally,
upload failed, retry later."
- **Redact before send**: API keys, Bearer tokens, cookies, passwords,
secrets, private account info.
- Triage flow: ask users to use the feedback page, **not** to send raw
`config/` or full log directories.
### Sensitive-info scan
Pre-commit:
```bash
git diff --cached
```
Periodic keyword scan:
```bash
git grep -nE "sk-|hf_|Bearer |apiKey|ANTHROPIC_API_KEY|OPENAI_API_KEY|password|secret" \
-- ':!*.lock' ':!vendor/**' ':!**/__pycache__/**'
```
Hits require **human judgment** — demo keys in comments and real keys
both match. Don't blind-commit, don't blind-delete.
If a real secret was committed:
1. Invalidate the key/token immediately.
2. Replace local config.
3. Notify collaborators.
4. Decide whether to rewrite Git history (`git filter-repo` or team-agreed
tool).
A "delete the key" commit alone is **not safe** — history still has it.
### Standard release flow
```bash
# 1. Sync
git checkout dev
git pull --ff-only <remote> dev
git status --short --branch
# 2. Check
<lint command>
<test command>
# 3. Bump version (every site on the project's bump checklist)
# 4. Commit + tag
git add <files>
git commit -m "chore: release vX.Y.Z"
git tag -a vX.Y.Z HEAD -m "<Project> VX.Y.Z"
git push <remote> dev
git push <remote> vX.Y.Z
# 5. Build
<build command>
# 6. Upload manifest + zips, verify size/sha256
```
### Product README required sections
On top of the standard README sections, product projects add:
- **Version status** — current source version, internal version,
collaboration branch, repo URL, migration source (if any), default
local service URL (if any), default output dir.
- **Quick start** — per platform (Windows / macOS / Linux): unpack,
start, access, stop.
- **Bundle contents** — what's inside the release zip.
- **Release-bump checklist** — which files contain version strings to
update on release.
### Minimum delivery checklist
Every "ready to ship" version must have:
- [ ] `<remote>/dev` has the corresponding commit
- [ ] `<remote>` has the corresponding tag (`v<x.y.z>`)
- [ ] `package.json` / `pyproject.toml` version correct
- [ ] UI version chip displays correctly
- [ ] Lint / typecheck / test all pass
- [ ] Distribution channel manifest points at correct platform zips
- [ ] manifest size / sha256 match actual files
- [ ] Release zip unpacks → start script → runs
- [ ] Zip contains **no** API keys, logs, user feedback, generated
outputs, or verification reports
Any unchecked → not "ready to ship."
### What new product projects need
Beyond the standard `AGENTS.md` + `CLAUDE.md` + `.claude/`:
1. **`docs/COLLABORATION_AND_RELEASE_WORKFLOW.md`** (or similar) — a
project-specific specialization referencing this section, listing
the project's bump checklist, build commands, and dist paths.
task_assistant's is the reference example.
2. **`scripts/build-release.*`** — outputs zip + updates `manifest.json`.
3. **Bump checklist** — single source of truth in `AGENTS.md` or the
workflow doc above.
4. **`CHANGELOG.md`** — one entry per version, semver order, user-visible
changes.
YAGNI:
- Complex release tooling (Lerna, Changesets) — small team, manual is fine.
- Auto-generated release notes — good commit messages suffice.
- Multi-environment config systems — only when actually needed.
---
## 6. Planning cadence
1–3 person team. Lightest process that keeps us aligned.
### Weekly
- Async written sync (Monday 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 is the "blocked or unclear" lines.
### Per task
Before starting work that takes more than ~half a day:
1. Write a 5-line spec: *Goal / Why / Done when / Out of scope / Risks*.
2. Drop in PR description (draft PR fine) **before** writing code.
3. If AI does most of the typing, the spec is also the prompt.
After:
1. PR description matches what shipped.
2. Lessons future-you would want → Claude memory (feedback / project
types). See [Memory](#memory).
### Quarterly
Half a day to:
- Re-read this `AGENTS.md`. Open PRs for what's stale.
- Review skill catalog. Archive unused.
- Run `consolidate-memory` on personal memory files.
### What planning is *not*
- Not Jira tickets. Two people don't need a board.
- Not Gantt charts. Need one → building the wrong thing.
- Not status theater. Monday post is for spotting blocks, not proving
you worked.
---
## 7. Handoff
Task packages, deliverables, work transfers between team members or to
external consumers.
### Why this matters
Handoff failures cost more than the original work. A package that's
"obvious" to the author is a half day of confusion for the recipient.
Handoff is **part of the deliverable**, not afterthought packaging.
### Two kinds
- **Internal** — passing work to a teammate or future-you. Branch, PR,
half-finished prototype.
- **External** — versioned artifact to a partner / customer / downstream.
Zip, dataset, release.
Both use
[`templates/HANDOFF_CHECKLIST.template.md`](templates/HANDOFF_CHECKLIST.template.md).
External has higher bar.
### Task package layout
```
<package>/
├── README.md ← what this is, who it's for, how to use
├── CHANGELOG.md ← what changed since 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"
}
```
Can't fill a field → `null` and explain in README. **Never make one up.**
### Internal handoff
Before handoff:
- PR description is current. Summary describes what shipped, not what
was attempted.
- Test plan in PR template filled honestly. Untested → say so, don't
bury.
- Surprising AI-assisted decisions → `## Notes for reviewer`. "AI tried
X first, didn't work because Y, working approach is Z" — saves the
reviewer a re-derivation.
- Local-only state (env vars, scratch data) documented or scripted.
"Works on my machine" is not a handoff.
The recipient should be able to: `git checkout` the branch → read PR
description → run test plan → form an opinion — **without messaging you.**
### External handoff (additional bar)
- **Reproducibility.** Someone with source access can rebuild from the
commit hash in `manifest.json`. Test once before first release.
- **Verification report.** Machine-checkable (JSON or similar) showing
pre-ship checks passed.
- **Provenance.** AI-generated → record model and human-in-loop steps.
For debugging six months later, not ceremony.
- **License & attribution.** Even for internal partners.
### What not to ship
- Files >500 MB without a delivery-channel conversation.
- Real PII unless that's 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
1. Read the README first, fully. Resist running scripts.
2. Run the verification report. Fails → stop and message the sender
before doing anything else.
3. Note any surprise — naming, missing files, version mismatch — and
send back within a day. Drift gets worse with silence.
---
## Working directory expectations (this repo)
- Small repo (~10 files). `Read` everything before acting; no need to
spawn a sub-agent for exploration.
- Don't introduce `package.json`, `Makefile`, CI configs, or other
toolchain files unless explicitly asked. This is a docs repo.
+1 -46
View File
@@ -1,46 +1 @@
# 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.
@AGENTS.md
-58
View File
@@ -1,58 +0,0 @@
# team-guide
> 中文版:[README.md](README.md)
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
Releases are tagged by date: `YYYYMMDD` (e.g. `20260520`). Each tag is a
snapshot of `main` from that day, suitable for "this is the version we
agreed to follow." See `docs/03-git-workflow.md` for the tagging rules.
- Latest tag: see [`git tag --sort=-creatordate`](https://git.simgreek.com/simgreek/team-guide/tags) on the remote
- `main` is always the working copy; tags are checkpoints
## License
Internal.
+48 -45
View File
@@ -1,68 +1,71 @@
# team-guide
> English: [README.en.md](README.en.md)
我们小团队的 AI 协作(vibe coding)开发约定。1–3 人规模,规则不多但都是真踩过的坑。
我们小团队的 AI 协作(vibe coding)开发约定。
1–3 人规模,英文写文档,规则不多但都是真踩过的坑。
完整规则在 [`AGENTS.md`](AGENTS.md)(英文,给 AI 看)——本仓库的**唯一规则来源**。
这份 README 是给人的导览,知道去哪查、怎么参与就行。
## 这个仓库是什么
## 怎么用
工作方式的唯一来源——不是项目代码,是**怎么干活**。覆盖:
1. **新成员** —— 读这份 README 五分钟,再扫一眼 [AGENTS.md](AGENTS.md) 的目录。具体规则用到再翻。
2. **新项目** —— 从 [`templates/`](templates/) 复制对应模板。新仓库根目录放 `AGENTS.md`,再放一行 `@AGENTS.md` 的 `CLAUDE.md`,让 Claude Code 和 Codex 读同一份。
3. **不同意某条规则** —— 在本仓库开 PR 改它,不要私下绕开。
- 怎么用 Claude Code(CLAUDE.md、permission、hook、memory、skill)
- 写代码时人和 AI 怎么分工(vibe coding 守则)
- Git 工作流(分支、commit、PR、review)
- Skill 管理与项目规划节奏
- 代码与产出风格(命名、注释、README、任务包、handoff)
## 语言策略
每篇都很短。一条规则要超过半页才能解释清楚的,多半还不是规则——是个待讨论项。
- **给人看的(中文)**:本 README、`templates/` 里给人填的(README、PR、handoff)。
- **给 AI 看的(英文)**:[`AGENTS.md`](AGENTS.md)、[`CLAUDE.md`](CLAUDE.md)、AI 专用模板。
- **Git 元数据(英文)**:commit、PR 标题、分支名、tag 注释。
理由:AI 工具和搜索更吃英文 metadata;规则只需要一份不需要两份;中文给人在入口处看到。
## 目录
```
team-guide/
├── README.md ← 中文版(你正在看)
├── README.en.md ← English version
├── CLAUDE.md ← Claude Code 在本仓库工作时加载的上下文
├── docs/
│ ├── 01-vibe-coding.md ← 人 + AI 怎么分工
│ ├── 02-claude-code.md ← CLAUDE.md / permission / hook / memory / skill
│ ├── 03-git-workflow.md ← 分支、commit、PR、review、tag
│ ├── 04-skills-and-planning.md ← skill 目录 + 规划节奏
│ ├── 05-code-style.md ← 命名、注释、结构
│ └── 06-handoff.md ← 任务包、handoff 清单
└── templates/
├── CLAUDE.md.template
├── README.md.template
├── PR_DESCRIPTION.template.md
└── HANDOFF_CHECKLIST.template.md
├── README.md ← 你正在看(中文,给人)
├── AGENTS.md ← 全部规则(英文,给 AI)
├── CLAUDE.md ← 一行 @AGENTS.md import
└── templates/ ← 新项目脚手架
```
## 怎么用
1. **新成员** —— 先读 [`docs/01-vibe-coding.md`](docs/01-vibe-coding.md) 和 [`docs/03-git-workflow.md`](docs/03-git-workflow.md),其他当参考手册查。
2. **新项目** —— 从 `templates/` 复制模板到新仓库填上,再在新仓库根目录放一个 `CLAUDE.md` 指回这里。
3. **不同意某条规则** —— 在本仓库开 PR 改它,不要私下绕开。
## 文档语言约定
- 仓库内所有 `.md` 用**英文**,包括 commit message、PR 标题、tag 注释。
- 这个 README 提供中文入口;剩下的内容直接读英文版本。
- 跟外部团队/客户的交付物按对方语言来——本仓库的规则只管内部。
[`AGENTS.md`](AGENTS.md) 内含 7 大章:
项目背景与编辑规则 · Vibe coding · Claude Code & Codex 配置 ·
Git 工作流 · 代码与产出风格 · 产品类项目(semver、manifest、发版)·
规划节奏 · Handoff。
## 版本管理
按日期打 tag,格式 `YYYYMMDD`,比如 `20260520`。
按**项目类型**分两种 tag 风格:
- `main` 永远是当前工作副本,随时合并。
- 一天最多一个 tag。同一天有多次发布,用 `YYYYMMDD-N` 后缀(`20260520-2`)。
- Tag 一旦推到远端就不能改、不能删、不能 force-push。
- 大改写新 tag,不动旧 tag。
- 谁要"用某一版",告诉对方 tag 名(例:`team-guide @ 20260520`)就行。
- **规范类**(本仓库 team-guide、其他规约文档)—— 按日期 `YYYYMMDD`,比如 `20260520`。同一天多次发布加 `-N` 后缀(`20260520-2`)。从 `main` 打 tag。
- **产品类**(task_assistant、authoring-tool 这种有版本、有发行包的)—— semver `vX.Y.Z`,比如 `v0.2.4`。三处版本号必须同步:内部 `0.2.4` / 显示 `V0.2.4` / tag `v0.2.4`。从 `dev` 打 tag。
打 tag 的具体命令和场景见 [`docs/03-git-workflow.md`](docs/03-git-workflow.md) 的 Tagging 一节。
通用规则:
最近 tag 列表:[git.simgreek.com/simgreek/team-guide/tags](https://git.simgreek.com/simgreek/team-guide/tags)
- `main`(规范类)/ `dev`(产品类)永远是当前工作副本。
- 只用 annotated tag(`git tag -a`)。
- Tag 一旦推到远端就不能改、不能删、不能 force-push。错了切新的。
- 谁要"用某一版",告诉对方 tag 名(`team-guide @ 20260520`、`task_assistant @ v0.2.4`)就行。
具体命令、什么时候切 tag、产品项目发版细则——见 [`AGENTS.md`](AGENTS.md) 的 Git workflow 和 Product projects 两节。
## 几条最容易踩的线(速查)
完整版在 AGENTS.md,这里挑人最常忘的:
- 长 session 的上下文会污染输出,新任务开新 session
- 不读 diff 就 "looks good" 是 bug 上线的标准姿势
- 一个 session 不要同时让 Claude Code 和 Codex 改同一个文件
- AI 试同一个方案两次报同样的错——叫停,自己上
- 改了 `CLAUDE.md` / `AGENTS.md` 一边,另一边要在同一个 PR 里同步(本仓库已经用 `@AGENTS.md` 解决了,新项目要注意)
- 提交前 `git diff --cached` 扫一眼,密钥误提交的应急流程在 AGENTS.md 的 Sensitive-info scan 节
- 产品发版"必改字段清单"漏一处下版就漂移——清单写进项目自己的 AGENTS.md
## 远端
[git.simgreek.com/simgreek/team-guide](https://git.simgreek.com/simgreek/team-guide) ·
[tags 列表](https://git.simgreek.com/simgreek/team-guide/tags)
## License
-84
View File
@@ -1,84 +0,0 @@
# 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
@@ -1,129 +0,0 @@
# 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.
-137
View File
@@ -1,137 +0,0 @@
# 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.
## Tagging (versioning)
We tag by date: `YYYYMMDD` (e.g. `20260520`). Each tag is a snapshot of
`main` worth pointing at — "this is the version we agreed to follow."
Rules:
- Tag only on `main`. Tagging a feature branch is a smell.
- One tag per day max. If you cut a second one the same day, suffix with
`-N`: `20260520-2`, `20260520-3`.
- Tag messages are annotated, not lightweight. Use `git tag -a` and
write one or two sentences about what changed since the last tag.
- A tag, once pushed, is immutable. No deleting, no moving, no force-tag.
If the tag is wrong, cut a new one.
- Tag the commit, push the tag, and announce the tag name. That's the
release.
Cut a tag:
```bash
git checkout main
git pull --ff-only
git tag -a 20260520 -m "team-guide 20260520: bilingual README, dated tags"
git push origin 20260520
```
List / inspect:
```bash
git tag --sort=-creatordate # newest first
git show 20260520 # show what's in a tag
git log --oneline 20260513..20260520 # what changed between tags
```
When to cut a tag:
- The docs in this repo changed in a way teammates need to read.
- A template was added, removed, or restructured.
- A new convention is now in effect (not just proposed).
When NOT to cut a tag:
- Typo fixes, formatting, broken links → just push to `main`.
- Drafts under discussion → use a PR, don't tag.
## 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 deleting or moving tags after they've been pushed. Cut a new one
instead.
- 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
@@ -1,112 +0,0 @@
# 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
@@ -1,111 +0,0 @@
# 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
@@ -1,121 +0,0 @@
# 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.
+69
View File
@@ -0,0 +1,69 @@
# AGENTS.md — <project name>
<!--
Template. Copy into a new repo and fill the bracketed sections.
Sister file: CLAUDE.md (Claude Code reads that one). Keep them in sync.
Delete sections that don't apply. Keep total length under ~100 lines.
-->
## Project
<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.>
## Language policy
<If this project follows the team's bilingual policy, copy this:>
- Human-facing docs (README, `docs/*.md`, human-fillable templates) are
in Chinese.
- AI-facing files (`CLAUDE.md`, `AGENTS.md`, AI-only templates) are in
English.
- Commit messages, PR titles, branch names, tag annotations: English.
## Don'ts
<Things Codex / Claude / 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.>
## Sync
When you edit this file, also update `CLAUDE.md` (and vice versa). The
two files describe the same project to different tools.
+18 -2
View File
@@ -2,10 +2,11 @@
<!--
Template. Copy into a new repo and fill the bracketed sections.
Sister file: AGENTS.md (Codex reads that one). Keep them in sync.
Delete sections that don't apply. Keep total length under ~100 lines.
-->
## What this project is
## Project
<One or two sentences. What does it do, who is it for.>
@@ -40,9 +41,19 @@ Key files:
<Anything that's not obvious from reading the code. Naming patterns,
where to add new features, what's auto-generated, etc.>
## Language policy
<If this project follows the team's bilingual policy, copy this:>
- Human-facing docs (README, `docs/*.md`, human-fillable templates) are
in Chinese.
- AI-facing files (`CLAUDE.md`, `AGENTS.md`, AI-only templates) are in
English.
- Commit messages, PR titles, branch names, tag annotations: English.
## Don'ts
<Things Claude or a new contributor has gotten wrong before.
<Things Claude / Codex / a new contributor has gotten wrong before.
One line each. Add to this list as you discover them.>
- Don't <…>
@@ -51,3 +62,8 @@ One line each. Add to this list as you discover them.>
## External resources
<Links to dashboards, related repos, docs, ticket trackers.>
## Sync
When you edit this file, also update `AGENTS.md` (and vice versa). The
two files describe the same project to different tools.
+44 -50
View File
@@ -1,71 +1,65 @@
# Handoff checklist — <package or branch name>
# Handoff 清单 — <包名或分支名>
<!--
Fill this out before declaring the handoff complete.
Ships inside the package for external handoffs.
Lives in the PR description for internal handoffs.
交付前填完整。外部 handoff 一起放进包里;内部 handoff 放进 PR
description。正文中文,技术字段(commit hash、ISO 时间戳等)保留
英文格式。
-->
## 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>
- **名称**:<包名或分支名>
- **版本**:<比如 v0.5.0 或 commit sha 或 tag 比如 20260520>
- **生成时间**:<ISO 时间戳>
- **源仓库**:<url>
- **源 commit**:<full sha>
- **作者 / handoff owner**:<name>
- **接收方**:<name 或团队>
## 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
- [ ] `README.md` —— 这是什么、怎么用
- [ ] `CHANGELOG.md` —— 跟上一版的差异(首发就写"first release")
- [ ] `manifest.json` —— 机器可读元数据,所有字段都填了或显式 null
- [ ] `VERIFICATION.md` —— 检查了什么、结果如何
- [ ] 数据 / 产物 —— 真正的交付物
- [ ] 脚本 —— 仅限于使用本包必须的脚本
## 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
- [ ] 记录数 / 文件数与预期一致
- [ ] Checksum 已计算并记录
- [ ] 合理性检查通过(列出来)
- [ ] 不含密钥、`.env`、credential
- [ ] 不含 PII(除非交付协议里就明确包含)
- [ ] 总大小在传输渠道可接受范围
Verification report path: `<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
- [ ] 已确认有源仓库访问的人能从 `source_commit` 重建产物(写明
谁测的、什么时候测的)
- [ ] 构建 / 生成命令写在 `README.md` 里
- [ ] 外部依赖锁版本
## Provenance (if AI-assisted)
## 来源(AI 协助生成时填)
- 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>
- 使用的模型:<比如 claude-opus-4-7、gpt-5-codex>
- 人工审核步骤:<人审 / 批准了哪些部分>
- 值得标注的 AI 决策:<半年后产物有问题时会想知道的事>
## 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>
- [ ] 先读 `README.md`
- [ ] 跑验证报告 —— 不通过就停下来联系发送方
- [ ] <X 天>内确认收到
- [ ] 任何意外(缺文件、版本不对、命名异常)<X 天>内反馈给发送方
+27 -30
View File
@@ -1,52 +1,49 @@
<!--
PR description template. Title goes in the PR title field, not here.
Title format: <area>: <imperative summary under 70 chars>
PR description 模板。标题写在 PR 标题栏,不在这里。
标题格式:<area>: <祈使句小结,70 字符以内>。英文。
正文中文。
-->
## Summary
## Summary(小结)
<One sentence describing what this PR does. Then 1–3 bullets if needed.>
<一句话说清这个 PR 干了什么。需要的话再加 1–3 条 bullet。>
- <bullet>
- <bullet>
## Why
## 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.>
<动机。解决什么问题、落实什么决策、修哪个 bug。如果挂着 issue
或者之前的讨论,链上来。>
## What changed
## 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.>
<列出实际改动,跨多个区域时按区域分组。写事实就行——diff 是真相
来源,这只是地图。>
- `<file or area>` — <change>
- `<file or area>` — <change>
- `<文件或区域>` — <改动>
- `<文件或区域>` — <改动>
## Test plan
## 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.>
<勾选式 checklist。做了的勾 `[x]`,没做的留 `[ ]` 并在下面解释为什么。
诚实——"没测"可以接受,"声称测了但没测"不行。>
- [ ] Unit tests pass locally (`<command>`)
- [ ] Lint / typecheck pass (`<command>`)
- [ ] <feature-specific check>
- [ ] <feature-specific check>
- [ ] 单元测试本地通过(`<command>`)
- [ ] Lint / typecheck 通过(`<command>`)
- [ ] <功能特定的检查>
- [ ] <功能特定的检查>
## Out of scope
## Out of scope(范围外)
<Things you noticed but explicitly chose not to fix in this PR. Helps
reviewers not bring them up.>
<你注意到但**显式选择不在这个 PR 修**的东西。帮 reviewer 不要在这些
点上提出来。>
## Notes for reviewer
## Notes for reviewer(给 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 协作决策、走过的捷径,或者"我考虑
过 X 但选了 Y 因为 Z"。没什么可写就删掉这一节。>
---
🤖 AI-assisted with Claude Code.
🤖 AI 协助完成(Claude Code / Codex)。
+24 -24
View File
@@ -1,62 +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.>
<一段话。比 tagline 多点细节。谁会用、解决什么问题、明确**不**做
什么。>
## 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).
代码在 `<dir>`。测试在 `<dir>`。架构细节看 [docs/](docs/)(没有就
删掉这行)。
## Configuration
## 配置
<Env vars, config files, secrets. Point to a `.env.example` if there is
one. Don't list real values.>
<env var、配置文件、密钥。指向 `.env.example` 如果有的话。不写真实
值。>
## Data sources / outputs
## 数据来源 / 流向
<Only if non-obvious. Where does input come from, where do outputs go.>
<仅当不显然时写。输入从哪来,输出到哪去。>
## Related
## 相关链接
- <link>
- <link>
- <链接>
- <链接>
## License
<Internal / MIT / etc.>
<Internal / MIT / 等等。>