7 Commits
Author SHA1 Message Date
阿白叔andClaude Opus 4.7 161559a83d docs: add new-project bootstrap prompt to README
Add a copy-pasteable prompt for humans to drop into Claude Code /
Codex when starting a new project. The prompt makes the AI fetch
team-guide, ask consolidated questions, scaffold project files
(AGENTS.md, CLAUDE.md, .gitignore, .gitattributes, .env.example,
README.md), and stop for confirmation before first commit.

Also covers the existing-project case (补规范) by swapping the
scaffolding step.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-21 13:15:40 +08:00
阿白叔andClaude Opus 4.7 17671b2b22 docs: add library/nodejs-project SOP with encoding checks
8-phase AI execution sequence for Node.js / Next.js projects:
entry → frame → sync → edit → encoding → verify → commit → push
→ release. Phase 4 covers BOM / CRLF / non-UTF-8 detection and
fixes — these are the most common silent corruption when AI edits
files on Windows-default encoding systems.

- library/nodejs-project/SPEC.md (new)
- library/README.md catalog updated
- AGENTS.md §5 Team library entry list updated

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-21 12:31:14 +08:00
阿白叔andClaude Opus 4.7 c8ce92a2ed docs: refocus on AI behavior, drop human-only sections
team-guide is for AI to read at task start. Removed sections that
only describe human ceremonies and rewrote rules so AI can act on
them directly.

AGENTS.md:
- Replace §6 Planning cadence (Weekly/Quarterly/anti-Jira rhetoric)
  with §6 Per-task spec — the only planning rule AI actually executes.
- §1 Vibe coding rewritten to be AI-actionable: explicit spec
  requirement, observable stop-conditions (300-line / 5-file
  thresholds), self-verification 6 steps phrased as AI behaviors.
- §2 Claude Code & Codex config compressed: each rule = decision +
  one-line rationale, removed prose around skills/memory/sub-agents.
- §3 Git: drop branch owner-prefix rule, draft-PR rhythm, comment
  etiquette. Keep PR description structure and reviewer 5-step.
  Tag examples use <YYYYMMDD> placeholder so AI doesn't anchor on
  a specific date.
- §Editing rules: drop snark ("No 🚀 Getting started! energy") that
  could be misread; plain "No emoji".
- §Working directory: remove hardcoded "~10 files" count.

README.md:
- Drop "速查" cheatsheet (was for humans, redundant with AGENTS.md).
- Drop hardcoded tag examples (20260520).
- Trim positioning explanation in half.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-21 11:52:53 +08:00
阿白叔andClaude Opus 4.7 c5e6ebb534 docs: replace templates/ with library/, drop unaudited Product section
team-guide is now positioned as the external rulebook agents read at
project start: project AGENTS.md files reference team-guide rather
than duplicating its content.

- Delete templates/ (5 files). The only useful one — AGENTS.md
  skeleton — is now an inline code block in AGENTS.md §2. Handoff
  checklist also inlined into AGENTS.md §7.
- Remove the unaudited "Product projects" section (was AGENTS.md §5).
  Project repos document their own release scheme in their own
  AGENTS.md.
- Add library/ as a catalog for narrower specs.
- Seed library/git-upload/SPEC.md: what to commit / what not to,
  .gitignore baseline, sensitive-info scan, leaked-secret recovery.
- AGENTS.md gets a "How AI agents use this repo" intro and a §5 Team
  library section indexing library/.
- README.md updated to match: explicit "for AI" framing, library
  section, drop product-spec mentions.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 23:38:46 +08:00
阿白叔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
17 changed files with 1366 additions and 1082 deletions

No files matched your search

+720
View File
@@ -0,0 +1,720 @@
# 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.
## How AI agents use this repo
Before starting non-trivial work in any team project, an agent should:
1. **Read this `AGENTS.md`** — general rules (vibe coding, Git, code
style, planning, handoff).
2. **Scan [`library/README.md`](library/README.md)** — focused specs
for narrower topics. Read the entries that match the current task.
3. **Read the project's own `AGENTS.md`** — project-specific stuff
(how to run it, architecture, project-only don'ts). Project AGENTS.md
files do **not** repeat team-guide content; they reference it.
In short: team-guide is the external rulebook every project's agent
reads at task start. Project AGENTS.md files stay small and specific.
## 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.
- Keep AGENTS.md under ~600 lines. Past that, split a section into
`library/`.
- Examples beat prose. A 3-line code block beats a paragraph.
## Language policy
- **Human-facing**: Chinese — `README.md` only.
- **AI-facing**: English — this file, `CLAUDE.md`, anything under
`library/`.
- **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
AI writes most of the code. Humans steer: framing problems, making
decisions, deciding what's good enough. The point of AI assistance is
to skip typing, not to skip 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
- Stop AI when it's tried twice and is going in circles
- Sign off on commit messages and PR descriptions (AI drafts; human signs)
### Spec requirement
If the task description from the human is shorter than ~3 sentences and
the work touches more than one file, the AI must **stop and ask for a
5-line spec** before writing code:
```
Goal: <what should be true after this task>
Why: <one sentence>
Done when: <measurable acceptance>
Out of scope: <things explicitly not to touch>
Risks: <what could go wrong>
```
Don't infer the spec silently. Vague task + silent inference is the most
common cause of AI rework.
### Prompt habits (rules for human input that improve AI output)
- **Frame, don't dictate.** Goal + constraints + what's been ruled out.
Don't prescribe steps unless the steps are the point.
- **Name files.** "Fix the bug in `<repo>/<file>.py`" beats "fix the bug."
- **Say what done looks like.** Measurable phrasing — "tests pass and
the new flag defaults to off." Not "make it cleaner."
- **One task per session.** Unrelated asks → separate sessions.
- **Push back on bad output.** Point at the wrong part specifically.
### When AI must stop and surface to the human
AI stops driving and surfaces the situation to the human when:
- The same approach has failed twice with the same error.
- The task is asking AI to add code (validation, retry logic, defensive
guards) the spec didn't request.
- The current diff has grown past ~300 lines or touches >5 files when
the spec called for a narrower change.
- AI is about to do something irreversible (delete data, force-push,
rotate auth, drop a database, modify a production config).
In each case, AI summarizes the situation and asks for direction. Don't
keep iterating.
### Output verification (AI runs this on its own diffs before declaring done)
1. Does the build / typecheck pass?
2. Do tests pass — and do new tests actually exercise the new code?
3. Are there files in the diff outside the stated scope? If yes, justify
each or revert.
4. Did this PR add dependencies? If yes, name them in the summary.
5. Are there AI-generated comments restating what the code says? Delete.
6. For user-facing changes: state how the change was exercised end-to-end.
Type-check passing is not evidence of working software.
### Anti-patterns AI must avoid
- **Snowballing context.** Long single session covering multiple
unrelated tasks; stale assumptions leak across tasks.
- **Refactor drift.** "While I'm here, let me also clean up X." Open a
separate task instead.
- **Comment padding.** Adding obvious or restating comments to make a
diff look thorough.
- **Silent scope expansion.** Touching files not implied by the task
without flagging them in the summary.
---
## 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.
### Per-project AGENTS.md content
Order: **Project** (≤2 sentences) → **Run it** (bash blocks) →
**Architecture** (one paragraph + key files) → **Conventions specific
to this repo** → **Don'ts** (things AI got wrong here before).
Past 100 lines → split. Skeleton:
```markdown
# AGENTS.md — <project name>
> Reference: team-guide for cross-project rules. This file holds only
> what's specific to this project.
## Project
<one or two sentences>
## Run it
```bash
<install / run / test / lint commands>
```
## Architecture
<one paragraph: entry points, data flow, major modules>
Key files:
- `<path>` — <one-line role>
## Conventions specific to this repo
<naming patterns, where to add new features, what's auto-generated>
## Don'ts
- Don't <…>
```
`CLAUDE.md` in a new project is one line: `@AGENTS.md`.
### Permissions (Claude Code)
Default: prompt for risky, allow read-only. **Why:** keeps friction
low for safe ops while preserving review of mutations.
Allow without prompt: all `Read`/`Glob`/`Grep`, read-only Bash
(`git status`, `git diff`, `git log`, `git branch`, project test
runners).
Always prompt: `Edit`/`Write` outside the working tree; destructive
Bash (`rm`, `mv`, `git push`, `git reset --hard`, package installs);
any MCP tool hitting a remote service.
### Codex approval & sandbox
- **Approval**: default `on-request`. **Why:** unfamiliar repos and
shared machines need command-level review.
- **Sandbox**: default `workspace-write` + network off. Turn network
on only when fetching/installing, then off again.
- Personal Codex prefs go in `~/.codex/config.toml`, never committed.
### Hooks
AI does not reliably remember "from now on do X" across sessions —
hooks enforce automatically.
Use for: auto-format on edit, block writes to protected paths
(`.env`, generated files, `dist/`), auto-test after writing test files,
session-stop notifications.
Don't use for: one-off reminders, anything depending on AI judgment.
### Memory
Per-machine. Use for: who you are (User), corrections that should
persist across sessions with the *why* (Feedback), facts about
ongoing work that aren't in code (Project), pointers to external
resources (Reference).
Memory is personal and per-machine — never substitute for AGENTS.md.
Task-scoped state goes in plans or PR descriptions, not memory.
### Skills
Locations: user (`~/.claude/skills/`), project
(`<repo>/.claude/skills/`), plugin marketplace.
Promote a workflow to a skill when **all three** hold: done the same
way 3+ times, steps stable enough to write down, someone else would do
it the same way given the spec.
Skill design:
- One skill, one job. Branching skills are two skills.
- Verb-phrase names (`review-pr`, `cut-release`), not nouns
(`pr-helper`).
- Description tells the model **when to invoke**, not what the skill
does.
- `SKILL.md` under 200 lines.
Recommended installs (read each skill's own description for what it
does):
```
consolidate-memory simplify fewer-permission-prompts review security-review
```
### Sub-agents
Spawn one when: cross-file search and you don't want results in main
context, second independent read on a design or diff, genuinely parallel
work (e.g. three options to research). Don't spawn for tasks doable 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.
### Mixing Claude Code + Codex
Both fine. **Don't** run two tools editing the same file simultaneously
— overwrites are hard to trace.
Mild preferences: docs/specs and large refactors → Claude Code (plan
mode, sub-agents); narrow edits and quick test runs → Codex CLI
(faster startup); in-IDE inline → Codex IDE plugin or Cursor.
---
## 3. Git workflow
### Branches
- `main` (spec repos) / `dev` (product repos) is always shippable. No
direct pushes.
- Feature branches: `<short-slug>`, lowercase, hyphenated. Project may
prefix with owner (`<owner>/<slug>`) — follow the project's existing
convention.
- 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.
- Imperative: "add", "fix", "rename" — not "added" / "adding".
- 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 structure: **Summary** (1 sentence + bullets if needed) /
**Why** / **What changed** (bulleted by file or area) / **Test plan**
(checkbox list, honest about what was and wasn't tested) /
**Out of scope** (optional) / **Notes for reviewer** (optional, for
surprising AI decisions). Add an `AI-assisted` trailer for
AI-assisted PRs.
- First push of a feature branch uses `-u`.
### Review (when AI is reviewer)
When AI reviews a PR, run these checks in order:
1. Does the PR description match the actual diff? Flag surprises.
2. Read every changed file. Files outside the stated topic → flag with
"this file is not implied by the description".
3. Run the change locally if correctness isn't obvious from reading.
4. Block until justified: new deps, schema changes, env var additions,
auth-touching code, anything affecting persisted data.
5. Output critical findings (merge-blockers) last in the review summary
so they're visually distinct from minor comments.
### Merging
- Squash for feature branches.
- Final squash message follows commit format.
- Delete the branch on merge.
### Tagging (this repo)
Tags are dated: `<YYYYMMDD>`, with `-N` suffix for same-day reissues
(e.g. `<YYYYMMDD>-2`). Tag from `main`.
Rules:
- 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.
- Max one tag per day; use `-N` for same-day reissues.
Cut a tag:
```bash
git checkout main && git pull --ff-only
git tag -a <YYYYMMDD> -m "team-guide <YYYYMMDD>: <summary>"
git push origin <YYYYMMDD>
```
Inspect:
```bash
git tag --sort=-creatordate
git show <YYYYMMDD>
git log --oneline <prev-tag>..<this-tag>
```
When to cut a tag:
- Rules changed in a way that affects how AI should behave on tasks.
- A `library/` entry was added, removed, or restructured.
When **not** to cut a tag:
- Typos, formatting, link fixes → just push to `main`.
- Drafts under discussion → use a PR.
Project repos in the workspace use their own tag schemes (typically
semver `vX.Y.Z`). Each project documents its own scheme in its own
`AGENTS.md`.
### Don'ts
- No `git push --force` to `main` / `dev` — ever.
- 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 explicit
approval (Git LFS or out-of-band).
- No `git add .` / `git add -A` when untracked files are present that
weren't explicitly part of the task. 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.
Shorter than this is fine — drop sections that don't apply.
### 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. Team library
Narrower specs that don't fit cleanly in this file live under
[`library/`](library/). Catalog: [`library/README.md`](library/README.md).
When an agent picks up a task, it should scan the catalog after reading
this file and read entries that match. Each entry leads with a "When
to read this" section so the decision is fast.
Current entries:
- [`library/git-upload/`](library/git-upload/SPEC.md) — what to commit,
what not to, how to recover from leaked secrets.
- [`library/nodejs-project/`](library/nodejs-project/SPEC.md) — task
execution SOP for Node.js / Next.js projects (entry → frame → sync →
edit → encoding → verify → commit → push → release).
Promotion criteria, layout, and adding rules: see
[`library/README.md`](library/README.md).
---
## 6. Per-task spec
Before AI writes code on a task that touches more than one file:
1. Confirm or produce a 5-line spec.
```
Goal: <what should be true after this task>
Why: <one sentence>
Done when: <measurable acceptance>
Out of scope: <things explicitly not to touch>
Risks: <what could go wrong>
```
2. Put the spec at the top of the PR description (draft PR is fine)
**before** writing code.
3. Reuse the spec as the AI prompt when handing the task off.
After the task ships:
- Update the PR description to match what actually shipped (not what
was originally proposed).
- Lessons future tasks would want → Claude memory (feedback / project
types). See [Memory](#memory).
---
## 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 the [handoff checklist](#handoff-checklist) below. 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.
### Handoff checklist
Copy into the package (external handoff) or PR description (internal).
Fill it before declaring handoff done.
```markdown
## Identity
- Name:
- Version: <e.g. v0.5.0 or commit sha or tag>
- Generated at: <ISO timestamp>
- Source repo:
- Source commit: <full sha>
- Owner: <name>
- Recipient: <name or team>
## Contents
- [ ] README.md — what this is, how to use it
- [ ] CHANGELOG.md — diff vs previous version (or "first release")
- [ ] manifest.json — all fields filled or explicitly null
- [ ] VERIFICATION.md — what was checked, results
- [ ] Data / artifacts
- [ ] Scripts (only what's required to use the package)
## Verification
- [ ] Record / file counts match expected
- [ ] Checksums computed and recorded
- [ ] Sanity checks pass (list them)
- [ ] No secrets, .env, or credentials
- [ ] No PII unless explicitly part of deliverable
- [ ] Total size reasonable for delivery channel
## Reproducibility (external handoff only)
- [ ] Confirmed someone with repo access can rebuild from source_commit
- [ ] Build / generation command documented in README.md
- [ ] External dependencies pinned
## Provenance (if AI-assisted)
- Model used:
- Human-in-loop steps:
- Notable AI-assisted decisions:
## Known limitations
- <…>
## Recipient instructions
- [ ] Read README.md first
- [ ] Run verification report; if fails, stop and contact sender
- [ ] Confirm receipt within <X days>
- [ ] Report any surprises within <X days>
```
---
## Working directory expectations (this repo)
- This is a small docs-only repo. `Read` everything in scope before
acting; don't spawn a sub-agent for exploration.
- Don't introduce `package.json`, `Makefile`, CI configs, or other
toolchain files. There is no build/test/lint here.
+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.
+69 -46
View File
@@ -1,68 +1,91 @@
# team-guide
> English: [README.en.md](README.en.md)
我们小团队的 AI 协作开发约定。**给 AI 看的**——每个项目里 AI 开干前先读这里。
我们小团队的 AI 协作(vibe coding)开发约定。
1–3 人规模,英文写文档,规则不多但都是真踩过的坑。
完整规则在 [`AGENTS.md`](AGENTS.md)(英文)。这份 README 只是入口说明。
## 这个仓库是什么
## 这个仓库怎么用
工作方式的唯一来源——不是项目代码,是**怎么干活**。覆盖:
AI 进任何团队项目前的读取顺序:
- 怎么用 Claude Code(CLAUDE.md、permission、hook、memory、skill)
- 写代码时人和 AI 怎么分工(vibe coding 守则)
- Git 工作流(分支、commit、PR、review)
- Skill 管理与项目规划节奏
- 代码与产出风格(命名、注释、README、任务包、handoff)
1. [`AGENTS.md`](AGENTS.md) —— 团队通用规则
2. [`library/README.md`](library/README.md) —— 按当前任务挑相关条目读
3. 项目自己的 `AGENTS.md` —— 只放项目特定的东西
每篇都很短。一条规则要超过半页才能解释清楚的,多半还不是规则——是个待讨论项。
项目自己的 `AGENTS.md` **不重复** team-guide 里的内容,引用就行。
## 开新项目时丢给 AI 的提示词
复制下面这段,发给 Claude Code / Codex 当首句话——它会自己读完规则、问你必要信息、把项目脚手架(`AGENTS.md` / `CLAUDE.md` / `.gitignore` / `.gitattributes` / `.env.example`)建好,然后等你确认再开干。
```text
请按以下顺序为本项目做初始化:
1. 拉取并阅读 https://git.simgreek.com/simgreek/team-guide 的最新内容(至少读 AGENTS.md 和 library/nodejs-project/SPEC.md,如果是 Node 项目)。
2. 读完后,问我以下信息(一次性问完,不要一条一条挤牙膏):
- 项目名 / 一句话定位
- 技术栈(Node 版本、是否 Next.js / Express / 其他)
- 远端仓库地址(gitee / git.simgreek.com / 其他)
- 协作主分支名(main / dev)
- 是否产品项目(要发分发渠道);是的话,分发渠道是什么
- 需要哪些环境变量(只要变量名,不要值)
3. 拿到回答后,按 team-guide 的规范:
- git init(如果还没)+ 配 .gitignore(含 node_modules / .env* / 构建产物 / .claude/settings.local.json 等)
- 落 .gitattributes(强制 LF,.bat/.cmd 用 CRLF,二进制文件标 binary)
- 写 .env.example(仅变量名)
- 写项目根 AGENTS.md,遵循 team-guide §2 的骨架,引用 team-guide 而不是复制规则
- CLAUDE.md 写一行:@AGENTS.md
- 写 README.md(中文,给人看,三段:是什么 / 怎么跑 / 怎么配 .env)
4. 全部建好后,列出新增 / 修改的文件,告诉我下一步该 commit 哪些,等我确认再 git add + commit。第一个 commit 不要直接 push。
5. 整个过程严格遵守 team-guide 的「AI 必须停下问人」规则——任务模糊、范围敏感、远端冲突、--force、上传分发渠道,这些必须停下来确认。
```
老项目要补规范(已有代码、还没接入 team-guide),把第 3 步换成"补齐缺失的文件,不要覆盖现有的内容;冲突先列出来问我"。
## 语言策略
- **本 README 中文**——给人读的入口
- **AGENTS.md / CLAUDE.md / library/ 全英文**——给 AI 读
- **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 ← 全部团队规则(英文)
├── CLAUDE.md ← 一行 @AGENTS.md import
└── library/ ← 窄主题专项规范
├── README.md ← catalog
└── <topic>/SPEC.md
```
## 怎么用
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 提供中文入口;剩下的内容直接读英文版本。
- 跟外部团队/客户的交付物按对方语言来——本仓库的规则只管内部。
## 版本管理
按日期打 tag,格式 `YYYYMMDD`,比如 `20260520`。
本仓库按日期打 tag:`YYYYMMDD`(同一天多次发布加 `-N` 后缀)。tag 不可改、不可删、不可 force-push。
- `main` 永远是当前工作副本,随时合并。
- 一天最多一个 tag。同一天有多次发布,用 `YYYYMMDD-N` 后缀(`20260520-2`)。
- Tag 一旦推到远端就不能改、不能删、不能 force-push。
- 大改写新 tag,不动旧 tag。
- 谁要"用某一版",告诉对方 tag 名(例:`team-guide @ 20260520`)就行。
具体规则见 [`AGENTS.md`](AGENTS.md) §3 Git workflow。项目仓库自己用各自的 tag 方案(通常 semver `vX.Y.Z`),写在项目的 `AGENTS.md` 里。
打 tag 的具体命令和场景见 [`docs/03-git-workflow.md`](docs/03-git-workflow.md) 的 Tagging 一节。
## Library 怎么扩
最近 tag 列表:[git.simgreek.com/simgreek/team-guide/tags](https://git.simgreek.com/simgreek/team-guide/tags)
碰到跨项目的具体话题、塞进 AGENTS.md 会拖肿(比如"PII 处理"、"eval 报告格式"),就在 `library/<topic>/` 下写 `SPEC.md`。
收录标准(同时满足):
1. 至少踩过两次
2. 比 AGENTS.md 通用规则窄
3. 步骤稳定到能写下来
加一条要同时更新 [`library/README.md`](library/README.md) 的 catalog 表。
## 远端
[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.
+51
View File
@@ -0,0 +1,51 @@
# Team library
A small catalog of focused specs and reusable assets. Read the entries
that match the current task; ignore the rest.
This directory is **not** the team's general working agreements — those
live in [`../AGENTS.md`](../AGENTS.md). The library is for narrower,
deeper specs that would bloat AGENTS.md if inlined.
## How to use this
When starting a non-trivial task:
1. Read [`../AGENTS.md`](../AGENTS.md) (general rules).
2. Scan this catalog. If an entry matches your task, read its `SPEC.md`.
3. If nothing matches, proceed.
## Catalog
| Entry | Read it when… |
| ------------------------------------------- | -------------------------------------------------------------- |
| [`git-upload/`](git-upload/SPEC.md) | Pushing code to a remote, especially first push or new files |
| [`nodejs-project/`](nodejs-project/SPEC.md) | Working in any Node.js / Next.js project — task execution SOP |
(More entries will be added as the team encounters recurring questions
worth standardizing.)
## Adding to the library
Promote a topic to a library entry when **all** are true:
1. The topic has bitten us at least twice.
2. It's narrower than AGENTS.md general rules and would make AGENTS.md
bloated to inline.
3. Steps are stable enough to write down.
Layout for a new entry:
```
library/<entry-name>/
└── SPEC.md ← English, the actual spec
```
`SPEC.md` follows the same editing rules as AGENTS.md (one rule per
bullet, no emoji, examples beat prose, ~300 lines max). Lead with a
**When to read this** section so agents can decide quickly whether the
entry applies.
If a future entry needs scripts or skill packages, add them next to
`SPEC.md`. The catalog table above gets a one-line "read it when…" for
each new entry.
+287
View File
@@ -0,0 +1,287 @@
# git-upload — what to commit, what not to
## When to read this
- Pushing to a remote for the first time on a project.
- Adding a new file type the project hasn't committed before (data
dumps, generated artifacts, model weights, .env files, screenshots).
- About to run `git add .` or `git add -A`.
- Cleaning up a `.gitignore`.
- Suspect or confirmed a secret was committed.
This is a focused spec, not the full Git workflow. Branch / commit /
PR / tagging rules live in [`../../AGENTS.md`](../../AGENTS.md) §3.
## The first rule
`git status` and `git diff --cached` before every push. **Read every
file name in the staging list.** Most accidents happen because the
author didn't notice an extra file got staged.
## What goes in
Source and infrastructure for the project. Things that:
- Are written by humans (or AI under a human's review).
- Are reasonably small (text or small binaries — a few MB at most).
- Are the canonical version, not a derivative or cache.
Concretely:
- Source code, scripts, tests
- Configuration **templates** (e.g. `.env.example`) — never real values
- Schemas, fixtures, small reference datasets that are part of the project
- Documentation (Markdown, small images for docs)
- Lockfiles (`package-lock.json`, `poetry.lock`, `Cargo.lock`, etc.) —
always commit these
- Build / CI configuration
- License, README, CHANGELOG
## What stays out
### Secrets and credentials
**Never commit any of these, even once, even temporarily.**
- API keys, tokens, passwords (any provider)
- `.env`, `.env.local`, `.env.production`, `*.pem`, `*.key`, `id_rsa`,
`*.pfx`, `*.p12`
- OAuth client secrets, webhook signing keys
- Database connection strings with embedded passwords
- Cloud credentials (`~/.aws/credentials`, service account JSON)
- Personal access tokens in URLs (`https://user:TOKEN@host/repo.git`)
- Cookies, session tokens, signed JWTs from real users
A "delete the secret" commit later is **not enough** — the secret stays
in history. See [Recovering from a leaked secret](#recovering-from-a-leaked-secret).
### Generated and runtime files
These are derivatives — regenerable from sources, not source themselves.
```
# Build outputs
dist/ build/ out/ target/ .next/ .nuxt/
# Dependency caches
node_modules/ .venv/ venv/ __pycache__/ .pytest_cache/ .mypy_cache/
.tox/ .gradle/ vendor/ Pods/
# Editor / IDE state
.vscode/ .idea/ *.swp .DS_Store Thumbs.db desktop.ini
# Local runtime / logs
logs/ *.log tmp/ .cache/ runtime-temp/ feedback-records/
generated_*/ reports/
```
The exception: vendored dependencies that you **deliberately** want
under version control (offline / air-gapped builds). That's a project
decision documented in the project's AGENTS.md, not the default.
### Large binaries
> 5 MB → stop. Talk about Git LFS or out-of-band storage first.
Common offenders to scan for before pushing:
- Model weights (`.bin`, `.safetensors`, `.gguf`, `.ckpt`, `.pt`, `.onnx`)
- Datasets (`.parquet`, `.arrow`, `.zip`, `.tar.gz`, `.7z` over a few MB)
- Videos, raw images, audio
- Database dumps, full backups
- Vendor SDK installers
Once a large binary is in history, the repo is bloated forever (unless
you rewrite history). Catch it before push, not after.
### Personal / machine-specific files
- Personal editor settings — those go in `~/.<editor>` not the repo
- Agent personal config — `.claude/settings.local.json`,
`~/.codex/config.toml` (the personal one)
- Per-machine paths, hostnames, debug toggles
- Temporary scratch files, half-written notes
### User and customer data
- Real PII (names, emails, phone numbers from real people)
- Real internal records, customer logs, support tickets
- Anything covered by NDA or compliance scope
If sample data is needed for tests, generate it synthetically or use
public fixtures.
## .gitignore patterns
A baseline for most projects (adapt to the language):
```gitignore
# OS
.DS_Store
Thumbs.db
desktop.ini
# Editors
.vscode/
.idea/
*.swp
*~
# Secrets
.env
.env.*
!.env.example
*.pem
*.key
id_rsa*
*.pfx
*.p12
# Agent local state
.claude/settings.local.json
.claude/projects/
.claude/sessions/
# Python
__pycache__/
*.py[cod]
.venv/
venv/
.pytest_cache/
.mypy_cache/
# Node
node_modules/
npm-debug.log*
yarn-error.log
# Build outputs (uncomment what applies)
# dist/
# build/
# out/
# Logs / temp
*.log
tmp/
.cache/
```
Two rules for `.gitignore`:
1. **Be deliberate about negations** (`!.env.example` etc.) — they
override broader rules and are the source of "why isn't this file
ignored" confusion.
2. **`.gitignore` only ignores untracked files.** A file already in the
index keeps being tracked even if you add it to `.gitignore`. To
actually stop tracking it: `git rm --cached <file>` then commit.
## Staging discipline
`git add .` and `git add -A` are dangerous when there are unrecognized
untracked files. The safe pattern:
```bash
git status --short # see what's changed
git add <specific files> # stage by name
git diff --cached # read what's actually being committed
git commit -m "..."
```
If you have many related files and want to use a glob, prefer `git add
src/foo/` (a directory) over `git add .` (the world).
## Sensitive-info scan
Before push, especially when you've added new files:
```bash
git diff --cached
```
For periodic / pre-release scans across the working tree:
```bash
git grep -nE "sk-|hf_|Bearer |apiKey|ANTHROPIC_API_KEY|OPENAI_API_KEY|password|secret" \
-- ':!*.lock' ':!vendor/**' ':!**/__pycache__/**'
```
Hits need **human judgment** — demo keys in comments and real keys both
match the same regex. Don't blind-commit and don't blind-delete.
For a stronger sweep, use a dedicated tool (`gitleaks`, `trufflehog`,
or your platform's secret scanning). They have richer rule sets than
the regex above. Run them at least before any first-time push to a new
remote.
## Recovering from a leaked secret
When a real secret has been committed (and possibly pushed):
1. **Invalidate the secret immediately.** Rotate the key/token at the
provider before doing anything else. This is the only step that
actually makes the leak safe — everything below is cleanup.
2. Replace the secret locally. Move it to `.env` (which is gitignored)
or your secrets manager.
3. Notify collaborators. They need to know not to base work on the
compromised commit until history is rewritten.
4. Decide whether to rewrite history. For a public repo or one with a
short history, use `git filter-repo` (preferred over the deprecated
`filter-branch`) or your platform's secret-removal tooling. After
rewrite, force-push with team agreement and ask everyone to re-clone.
5. Document the incident briefly — what leaked, when, how, what was
done. Future-you will want this when a similar mistake happens.
A "delete the key" commit on top is **not safe**. The secret is still
in history and accessible to anyone who clones.
## URLs with embedded credentials
A common slip: pushing with a token-embedded URL writes the token into
`.git/config`:
```
remote "origin"
url = https://user:TOKEN@host/owner/repo.git
```
Fix: after pushing, reset the URL to the credential-free form and let
the credential helper handle auth:
```bash
git remote set-url origin https://host/owner/repo.git
```
Verify with `git remote -v`. The token also lives in shell history and
in any `.bash_history` / PowerShell history file — clear it if the
token is sensitive enough to warrant rotation.
## First push to a new remote
A short checklist when initializing a project:
- [ ] `.gitignore` covers secrets, build outputs, editor state, agent
local state
- [ ] No `.env` (or any `.env.*` other than `.env.example`) in the tree
- [ ] No files >5 MB in the tree (check with `find . -size +5M
-not -path "./.git/*"` or equivalent)
- [ ] `git status` shows only files you mean to commit
- [ ] `git diff --cached` reads cleanly — no surprise content
- [ ] Repo URL on the remote matches the one you intend; no token in
the URL
- [ ] Credential helper is configured (so you don't have to embed tokens
in URLs)
After first push: `git remote -v` should show a clean URL.
## Don'ts (summary)
- Don't `git add .` with unrecognized untracked files in the tree.
- Don't commit `.env`, secrets, tokens, or real credentials — ever, not
even temporarily.
- Don't commit large binaries (>5 MB) without a Git LFS conversation.
- Don't commit generated / cache directories.
- Don't commit real user data or PII.
- Don't try to "clean up" a leaked secret with a delete commit. Rotate
first, rewrite history if needed.
- Don't leave tokens in `.git/config` after a token-in-URL push.
- Don't `--no-verify` to skip pre-commit secret scans.
+238
View File
@@ -0,0 +1,238 @@
# nodejs-project — AI execution SOP
## When to read this
- Working in any Node.js / Next.js project (anything with a `package.json`).
- Initializing a new Node project.
- About to commit, push, or release a Node project.
This is the AI's task-execution sequence. Each phase is a concrete set
of commands or checks the AI runs **on its own** before declaring the
task done. The only points that pause for the human are flagged
explicitly.
## Phase 0 — Project entry
Run on first action in the repo:
```bash
ls AGENTS.md CLAUDE.md package.json .gitignore
node --version
cat package.json | grep -A 20 '"scripts"'
```
- **No `AGENTS.md`** → stop. Ask the human: "this project has no
AGENTS.md; create one before proceeding?"
- **No `.gitignore` or it's <100 bytes** → stop. The project is missing
basic ignore rules; flag before any commit.
- **`node --version` doesn't match what AGENTS.md says** → stop, ask.
## Phase 1 — Task framing
Trigger conditions, in order:
- Task description < 3 sentences AND scope > 1 file → ask for the
5-line spec (`Goal / Why / Done when / Out of scope / Risks`).
- Task touches: `package.json` deps, schema, auth, secrets, production
config, build scripts → confirm scope with human before any edit.
- Otherwise: write the implicit spec into the PR description draft and
proceed.
## Phase 2 — Pre-edit sync
```bash
git status # working tree clean?
git pull --ff-only # remote ahead?
```
- Working tree dirty with unrelated changes → stop, ask.
- `pull --ff-only` fails (diverged history) → stop, ask. Don't
force-pull, don't merge silently.
## Phase 3 — Edit & verify
After each meaningful change run:
```bash
npm run check # if defined
npm test # if defined
npx tsc --noEmit # for TypeScript / Next.js
```
For projects with `build-release` or similar build scripts: do **not**
run them automatically — they produce large artifacts. Run only when
the task is "release."
Failure handling:
- Fix the error, re-run.
- **Same error twice** → stop, surface to human. Don't keep retrying.
## Phase 4 — Encoding & line-ending checks
Run before staging any text file changes. Source code on this team is
**UTF-8 without BOM**, line endings follow the project's existing
convention (typically LF, except `.bat` / `.cmd` which need CRLF).
Detection commands:
```bash
# Find files with UTF-8 BOM (EF BB BF) — should be empty output
git diff --cached --name-only -z | xargs -0 -I{} sh -c \
'head -c 3 "{}" | od -An -tx1 | grep -q "ef bb bf" && echo "BOM: {}"'
# Find CRLF in source files that should be LF (skip .bat/.cmd)
git diff --cached --name-only -z | xargs -0 grep -lI $'\r' 2>/dev/null \
| grep -vE '\.(bat|cmd)$'
# Find non-UTF-8 bytes in source
git diff --cached --name-only -z | xargs -0 -I{} sh -c \
'iconv -f UTF-8 -t UTF-8 "{}" >/dev/null 2>&1 || echo "non-UTF8: {}"'
```
Hits → fix before commit:
- BOM in `.js` / `.mjs` / `.json` / `.md` / `.html` / `.css` → strip.
Node `JSON.parse` rejects BOM in `package.json`. Some bundlers ship
BOM into the output and break browsers.
- CRLF in `.js` / `.mjs` / `.ts` / `.tsx` / `.json` / `.md` / `.sh` →
convert to LF. CRLF in `.sh` makes the script silently fail on Linux.
- CRLF in `.bat` / `.cmd` → keep, this is correct.
- Non-UTF-8 bytes (typically GBK on Windows) → re-save the file as
UTF-8 in the editor. This is the most common silent corruption when
AI edits a Chinese-content file on a system with Windows-default
encoding — symptom is "好" appearing as "濂" or similar mojibake.
Editor / tool notes for the human:
- Set editor to UTF-8 default and save without BOM.
- VSCode: status bar bottom-right shows current file's encoding;
click to "Save with Encoding → UTF-8" if needed.
- `.gitattributes` baseline (commit it once per project):
```
* text=auto eol=lf
*.bat text eol=crlf
*.cmd text eol=crlf
*.png binary
*.jpg binary
*.zip binary
```
This forces normalization on commit and prevents future drift.
## Phase 5 — Pre-commit verification
```bash
git status
git diff --cached
```
The AI must read the entire `--cached` diff and answer in its own
output:
1. Build / typecheck pass?
2. Tests pass (or honestly: "didn't run because <reason>")?
3. Files outside the stated scope? List + justify each, or revert.
4. New deps? List them in PR description and Phase 1 confirmation.
5. AI-generated comments restating the code? Delete.
6. End-to-end exercised (for user-visible changes)?
Plus **Node-specific Phase 5 checks**:
- `package-lock.json` in diff but no change to `package.json` deps →
stop. This is usually IDE auto-install. Revert the lockfile diff.
- `package.json` deps changed but no lockfile diff → stop. Run
`npm install` once, commit lockfile in same commit.
- `.env` / `.env.local` / `.env.production` / `*.pem` / `*.key` in diff
→ **stop, do not commit**. Add to `.gitignore` if missing.
- `node_modules/` / `.next/` / `dist/` / `build/` / `out/` in diff →
stop. Gitignore is broken; fix before commit.
- Files >5 MB in diff (`git diff --cached --stat | awk '$3 > 5120'`) →
stop, ask human about LFS or out-of-band delivery.
- Any encoding hit from Phase 4 unresolved → stop.
## Phase 6 — Commit
```bash
git add <specific files> # NOT git add . / git add -A
git commit -m "<area>: <imperative summary under 60 chars>"
```
- Always include `Co-Authored-By: Claude <noreply@anthropic.com>` (or
the project's tool-specific trailer) for AI-assisted commits.
- One topic per commit. "and" in summary → split.
- English message.
## Phase 7 — Push
```bash
git push origin <branch>
```
- First push of a new feature branch: include `-u`.
- Branch is `main` or `dev` → **stop, ask human** before push.
- `--force` push → **stop, ask human**, regardless of branch. Quote the
reason and the branch back to the human.
## Phase 8 — Release (product projects only)
Only run when the task is explicitly "release vX.Y.Z." Skip otherwise.
```bash
# 1. Read project's AGENTS.md "release-bump checklist"
# 2. For each listed file: edit, then verify no stale version remains
git grep -nE 'V?[0-9]+\.[0-9]+\.[0-9]+' -- <changed-files>
# 3. Standard checks
npm run check
npm test
# 4. Commit + tag
git add <changed files>
git commit -m "chore: release vX.Y.Z"
git tag -a vX.Y.Z HEAD -m "<Project> VX.Y.Z"
git push origin <branch>
git push origin vX.Y.Z
# 5. Build
npm run release # or project's build script
# 6. List artifacts
ls -lh release/ # or wherever the build outputs
# 7. STOP — ask human:
# "Artifacts ready: <list>. Sizes: <sizes>. Upload to <distribution
# channel>?"
```
The upload step is **always human-confirmed**. It's the only
externally-visible irreversible action in the flow.
## Where the human pauses
In total, AI stops and asks the human only at:
- Phase 0: missing AGENTS.md
- Phase 1: vague task or scope-sensitive change
- Phase 2: dirty tree or diverged history
- Phase 3: same error twice
- Phase 4 / 5: encoding / lockfile / secret / large-file anomalies
- Phase 7: push to `main`/`dev` or `--force`
- Phase 8: distribution upload
Everything else is self-running.
## Quick reference (for AI to scan)
```
[entry] read AGENTS.md → no? stop.
[frame] vague task? → spec. scope-sensitive? → confirm.
[sync] git status / pull --ff-only.
[edit] npm run check / test / tsc. fail twice? stop.
[encode] no BOM / LF for src / CRLF for .bat / valid UTF-8.
[verify] git diff --cached → 6 questions + Node-specific 5.
[commit] git add by name. <area>: <imperative>.
[push] main/dev/force? stop. else push.
[release] follow project's bump checklist. STOP before upload.
```
-53
View File
@@ -1,53 +0,0 @@
# CLAUDE.md — <project name>
<!--
Template. Copy into a new repo and fill the bracketed sections.
Delete sections that don't apply. Keep total length under ~100 lines.
-->
## What this project is
<One or two sentences. What does it do, who is it for.>
## Run it
```bash
# install
<command>
# run
<command>
# test
<command>
# lint / typecheck
<command>
```
## Architecture
<One paragraph. Where are the entry points, how does data flow, what
are the major modules. Skip diagrams unless they save words.>
Key files:
- `<path>` — <one-line role>
- `<path>` — <one-line role>
## Conventions specific to this repo
<Anything that's not obvious from reading the code. Naming patterns,
where to add new features, what's auto-generated, etc.>
## Don'ts
<Things Claude or a new contributor has gotten wrong before.
One line each. Add to this list as you discover them.>
- Don't <…>
- Don't <…>
## External resources
<Links to dashboards, related repos, docs, ticket trackers.>
-71
View File
@@ -1,71 +0,0 @@
# Handoff checklist — <package or branch name>
<!--
Fill this out before declaring the handoff complete.
Ships inside the package for external handoffs.
Lives in the PR description for internal handoffs.
-->
## Identity
- **Name**: <package or branch name>
- **Version**: <e.g. v0.5.0 or commit sha>
- **Generated at**: <ISO timestamp>
- **Source repo**: <url>
- **Source commit**: <full sha>
- **Author / handoff owner**: <name>
- **Recipient**: <name or team>
## Contents
- [ ] `README.md` — describes what this is, how to use it
- [ ] `CHANGELOG.md` — what's different from the previous version (or
"first release")
- [ ] `manifest.json` — machine-readable metadata, all fields filled or
explicitly null
- [ ] `VERIFICATION.md` — what we checked, what passed
- [ ] Data / artifacts — the actual deliverable
- [ ] Scripts — only what's needed to use the package
## Verification
- [ ] Record / file counts match expected
- [ ] Checksums computed and recorded
- [ ] Sanity checks pass (list them)
- [ ] No secrets, `.env`, or credentials included
- [ ] No PII unless explicitly part of the deliverable
- [ ] Total size reasonable for delivery channel
Verification report path: `<path>`
## Reproducibility
- [ ] Confirmed someone with repo access can rebuild from
`source_commit` (note who tested this and when)
- [ ] Build / generation command documented in `README.md`
- [ ] External dependencies pinned to versions
## Provenance (if AI-assisted)
- Model used: <e.g. claude-opus-4-7>
- Human-in-the-loop steps: <which parts a human reviewed / approved>
- Notable AI-assisted decisions: <anything that would matter if the
output looks wrong six months from now>
## Known limitations
<Things that don't work, edge cases that aren't covered, follow-ups
that didn't make this version. Be specific. "Works on my machine" is
not a limitation, it's a problem to fix before shipping.>
- <…>
- <…>
## Recipient instructions
- [ ] Read `README.md` first
- [ ] Run the verification report — if it fails, stop and contact the
sender
- [ ] Confirm receipt within <X days>
- [ ] Report any surprises (missing files, version mismatch, naming)
back to the sender within <X days>
-52
View File
@@ -1,52 +0,0 @@
<!--
PR description template. Title goes in the PR title field, not here.
Title format: <area>: <imperative summary under 70 chars>
-->
## Summary
<One sentence describing what this PR does. Then 1–3 bullets if needed.>
- <bullet>
- <bullet>
## Why
<The motivation. What problem does this solve, what decision does it
implement, what bug does it fix. If this links to an issue or earlier
discussion, link it here.>
## What changed
<Bulleted list of the actual changes, grouped by area if it spans
multiple. Keep it factual — the diff is the source of truth, this is
just a map.>
- `<file or area>` — <change>
- `<file or area>` — <change>
## Test plan
<Bulleted checklist. Mark `[x]` for done, `[ ]` for didn't do (and
explain why below). Be honest — "didn't test" is acceptable, "claimed
tested but didn't" is not.>
- [ ] Unit tests pass locally (`<command>`)
- [ ] Lint / typecheck pass (`<command>`)
- [ ] <feature-specific check>
- [ ] <feature-specific check>
## Out of scope
<Things you noticed but explicitly chose not to fix in this PR. Helps
reviewers not bring them up.>
## Notes for reviewer
<Anything that surprised you, AI-assisted decisions worth flagging,
shortcuts taken, or "I considered X but went with Y because Z". Skip
this section if there's nothing notable.>
---
🤖 AI-assisted with Claude Code.
-62
View File
@@ -1,62 +0,0 @@
# <project name>
<One sentence. What this is, in plain language.>
## What it does
<One paragraph. Slightly more detail than the tagline. Who would use
it, what problem it solves, what it explicitly does not do.>
## Quick start
```bash
# clone
git clone <url>
cd <repo>
# install
<command>
# run
<command>
```
Expected output:
```
<a few lines of what the user should see>
```
## Development
```bash
# tests
<command>
# lint / typecheck
<command>
# format
<command>
```
Code lives in `<dir>`. Tests live in `<dir>`. See [docs/](docs/) for
deeper architecture notes (or delete this line if there are none).
## Configuration
<Env vars, config files, secrets. Point to a `.env.example` if there is
one. Don't list real values.>
## Data sources / outputs
<Only if non-obvious. Where does input come from, where do outputs go.>
## Related
- <link>
- <link>
## License
<Internal / MIT / etc.>