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>
This commit is contained in:
阿白叔andClaude Opus 4.7 committed 2026-05-21 11:52:53 +08:00
1 parent c5e6ebb534
commit c8ce92a2ed
2 files changed
+201 -312

No files matched your search

+177 -255
View File
@@ -36,8 +36,9 @@ read the change and would have written the same."
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.
- 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
@@ -74,9 +75,9 @@ When starting a new project, prefer the single-file approach: write
### 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.
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
@@ -96,59 +97,72 @@ making decisions, deciding what's good enough. We're not racing the AI
- 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)
- Stop AI when it's tried twice and is going in circles
- Sign off on commit messages and PR descriptions (AI drafts; human signs)
If a task feels like it's drifting toward "AI decides", stop and write
a spec yourself first.
### Spec requirement
### Prompt habits
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:
- **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.
```
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>
```
### When to take over
Don't infer the spec silently. Vague task + silent inference is the most
common cause of AI rework.
Stop letting AI drive when:
### Prompt habits (rules for human input that improve AI output)
- 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.
- **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 you take over, write *why* in the PR description so the next person
doesn't repeat the loop.
### When AI must stop and surface to the human
### Verifying AI output
AI stops driving and surfaces the situation to the human when:
Treat every AI diff like a fast junior's PR:
- 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).
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.
In each case, AI summarizes the situation and asks for direction. Don't
keep iterating.
### Anti-patterns
### Output verification (AI runs this on its own diffs before declaring done)
- **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.
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.
---
@@ -158,64 +172,49 @@ Treat every AI diff like a fast junior's PR:
```
<repo>/
├── AGENTS.md ← canonical spec, committed
├── CLAUDE.md ← committed, single line: @AGENTS.md
├── 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.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
### Per-project AGENTS.md content
In this order:
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).
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."
Skeleton to copy into a new project's `AGENTS.md`:
Past 100 lines → split. Skeleton:
```markdown
# AGENTS.md — <project name>
> Reference: team-guide (https://git.simgreek.com/simgreek/team-guide)
> for cross-project rules. This file holds only what's specific to
> this project.
> 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 <…>
```
@@ -223,143 +222,93 @@ Key files:
### Permissions (Claude Code)
Default: prompt for risky, allow read-only freely.
Default: prompt for risky, allow read-only. **Why:** keeps friction
low for safe ops while preserving review of mutations.
In `.claude/settings.json`, allow without prompting:
Allow without prompt: all `Read`/`Glob`/`Grep`, read-only Bash
(`git status`, `git diff`, `git log`, `git branch`, project test
runners).
- 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.
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` (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.
- **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
Hooks enforce rules automatically. AI **does not reliably remember**
"from now on do X" across sessions; hooks do.
AI does not reliably remember "from now on do X" across sessions —
hooks enforce automatically.
Use hooks for:
Use for: auto-format on edit, block writes to protected paths
(`.env`, generated files, `dist/`), auto-test after writing test files,
session-stop notifications.
- 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.
Don't use for: one-off reminders, anything depending on AI judgment.
### Memory
Per-machine memory system. Use it for:
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).
- **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.
Memory is personal and per-machine — never substitute for AGENTS.md.
Task-scoped state goes in plans or PR descriptions, not memory.
### Skills
Skills live in three places:
Locations: user (`~/.claude/skills/`), project
(`<repo>/.claude/skills/`), plugin marketplace.
- **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.
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`, `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.
- 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:
Recommended installs (read each skill's own description for what it
does):
```
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
consolidate-memory simplify fewer-permission-prompts review security-review
```
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.
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. Stale context
leaks in.
- Don't `--continue` yesterday's session for a new topic.
### Tool selection (mixing Claude Code + Codex)
### Mixing Claude Code + Codex
Both fine; mild preferences:
Both fine. **Don't** run two tools editing the same file simultaneously
— overwrites are hard to trace.
- **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.
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.
---
@@ -368,10 +317,10 @@ are hard to trace.
### 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.
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
@@ -382,10 +331,8 @@ are hard to trace.
<optional body — what changed and why, not how>
```
- `<area>` is a directory or component, lowercase: `eval-agent`,
`task_assistant`, `docs`, `git-workflow`.
- `<area>` is a directory or component, lowercase.
- 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.
@@ -404,42 +351,35 @@ task_assistant: drop unused legacy export path
- 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) / **Out of scope** (optional) / **Notes for
reviewer** (optional, for surprising AI decisions). Add a
`🤖 AI-assisted` trailer for AI-assisted PRs.
(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`.
- Open as draft once runnable. Review-as-you-go beats review-at-the-end.
### Review
### Review (when AI is reviewer)
Every PR reviewed before merge — own AI-assisted PRs included.
When AI reviews a PR, run these checks in order:
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.
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. Merge commits reserved for integration.
- Squash for feature branches.
- Final squash message follows commit format.
- Delete the branch on merge.
### Tagging
### Tagging (this repo)
Tags are dated: `YYYYMMDD`, with `-N` suffix for same-day reissues
(`20260520-2`). Tag from `main`.
Tags are dated: `<YYYYMMDD>`, with `-N` suffix for same-day reissues
(e.g. `<YYYYMMDD>-2`). Tag from `main`.
Rules:
@@ -447,29 +387,28 @@ Rules:
- 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.
- 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 20260520 -m "team-guide 20260520: bilingual policy"
git push origin 20260520
git tag -a <YYYYMMDD> -m "team-guide <YYYYMMDD>: <summary>"
git push origin <YYYYMMDD>
```
Inspect:
```bash
git tag --sort=-creatordate
git show 20260520
git log --oneline 20260513..20260520
git show <YYYYMMDD>
git log --oneline <prev-tag>..<this-tag>
```
When to cut a tag:
- Docs changed in a way teammates need to re-read.
- A new convention is now in effect (not just proposed).
- A library/ entry was added, removed, or restructured.
- 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:
@@ -482,15 +421,14 @@ semver `vX.Y.Z`). Each project documents its own scheme in its own
### Don'ts
- No `git push --force` to `main`. Period. To your own branch only if
certain nobody pulled it.
- 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 a Git LFS
conversation.
- No `git add .` / `git add -A` when there are unrecognized untracked
files. Stage by name.
- 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.
---
@@ -598,46 +536,30 @@ Promotion criteria, layout, and adding rules: see
---
## 6. Planning cadence
## 6. Per-task spec
1–3 person team. Lightest process that keeps us aligned.
Before AI writes code on a task that touches more than one file:
### Weekly
1. Confirm or produce a 5-line spec.
- 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.
```
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>
```
### Per task
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.
Before starting work that takes more than ~half a day:
After the task ships:
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.
- 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).
---
@@ -789,7 +711,7 @@ Fill it before declaring handoff done.
## Working directory expectations (this repo)
- Small repo (~10 files). `Read` everything before acting; no need to
spawn a sub-agent for exploration.
- 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 unless explicitly asked. This is a docs repo.
toolchain files. There is no build/test/lint here.
+24 -57
View File
@@ -1,87 +1,54 @@
# team-guide
我们小团队的 AI 协作(vibe coding)开发约定。1–3 人规模,规则不多但都是真踩过的坑。
我们小团队的 AI 协作开发约定。**给 AI 看的**——每个项目里 AI 开干前先读这里。
完整规则在 [`AGENTS.md`](AGENTS.md)(英文,给 AI 看)——本仓库的**唯一规则来源**。
这份 README 是给人的导览,知道去哪查、怎么参与就行。
完整规则在 [`AGENTS.md`](AGENTS.md)(英文)。这份 README 只是入口说明。
## 这个仓库给谁用
## 这个仓库怎么用
**给 AI 用**。每个团队项目里 AI 开干前应该先读 team-guide:
AI 进任何团队项目前的读取顺序:
1. 读 [`AGENTS.md`](AGENTS.md)——团队通用规则
2. 扫 [`library/README.md`](library/README.md)——按当前任务挑相关条目读
3. 再读项目自己的 `AGENTS.md`——只放项目特定的东西
1. [`AGENTS.md`](AGENTS.md) —— 团队通用规则
2. [`library/README.md`](library/README.md) —— 按当前任务挑相关条目读
3. 项目自己的 `AGENTS.md` —— 只放项目特定的东西
项目自己的 `AGENTS.md` **不重复**这里的规则,引用就行,保持小而具体。
## 怎么用(人)
1. **新成员** —— 读这份 README 五分钟,再扫一眼 [AGENTS.md](AGENTS.md) 的目录。具体规则用到再翻。
2. **新项目** —— 在新仓库根目录放 `AGENTS.md`(骨架在 [AGENTS.md](AGENTS.md) 的 Claude Code & Codex 节),再放一行 `@AGENTS.md` 的 `CLAUDE.md`。让两边 AI 工具读同一份项目说明。
3. **不同意某条规则** —— 在本仓库开 PR 改它,不要私下绕开。
项目自己的 `AGENTS.md` **不重复** team-guide 里的内容,引用就行。
## 语言策略
- **给人看的(中文)**:本 README。
- **给 AI 看的(英文)**:[`AGENTS.md`](AGENTS.md)、[`CLAUDE.md`](CLAUDE.md)、`library/` 下所有内容。
- **Git 元数据(英文)**:commit、PR 标题、分支名、tag 注释。
理由:AI 工具和搜索更吃英文 metadata;规则只需要一份不需要两份;中文给人在入口处看到。
- **本 README 中文**——给人读的入口
- **AGENTS.md / CLAUDE.md / library/ 全英文**——给 AI 读
- **commit、PR 标题、分支名、tag 注释全英文**——AI 工具和搜索吃英文 metadata 更准
## 目录
```
team-guide/
├── README.md ← 你正在看(中文,给人)
├── AGENTS.md ← 全部团队规则(英文,给 AI)
├── README.md ← 中文入口(你正在看)
├── AGENTS.md ← 全部团队规则(英文)
├── CLAUDE.md ← 一行 @AGENTS.md import
└── library/ ← 窄主题专项规范目录
└── library/ ← 窄主题专项规范
├── README.md ← catalog
└── git-upload/ ← 第一篇:什么该传什么不该传
└── SPEC.md
└── <topic>/SPEC.md
```
[`AGENTS.md`](AGENTS.md) 内含:
项目背景 · 编辑规则 · 语言策略 · Vibe coding · Claude Code & Codex 配置 ·
Git 工作流 · 代码与产出风格 · Team library 索引 · 规划节奏 · Handoff。
## Library 怎么扩
碰到一个跨项目的具体话题、AGENTS.md 里塞进去会拖肿(比如"git 上传到底什么该传"、"PII 处理"、"eval 报告格式"),就在 `library/` 下开一个子目录写 `SPEC.md`。
收录标准(同时满足):
1. 至少踩过两次。
2. 比 AGENTS.md 通用规则窄,inline 进去会拖肿。
3. 步骤稳定到能写下来。
每加一条在 [`library/README.md`](library/README.md) 的 catalog 表里加一行"什么时候读它"。
## 版本管理
本仓库(规范类)按日期打 tag:`YYYYMMDD`,比如 `20260520`。同一天多次发布加 `-N` 后缀(`20260520-2`)。从 `main` 打 tag。
本仓库按日期打 tag:`YYYYMMDD`(同一天多次发布加 `-N` 后缀)。tag 不可改、不可删、不可 force-push。
通用规则:
具体规则见 [`AGENTS.md`](AGENTS.md) §3 Git workflow。项目仓库自己用各自的 tag 方案(通常 semver `vX.Y.Z`),写在项目的 `AGENTS.md` 里。
- `main` 永远是当前工作副本。
- 只用 annotated tag(`git tag -a`)。
- Tag 一旦推到远端就不能改、不能删、不能 force-push。错了切新的。
- 谁要"用某一版",告诉对方 tag 名(`team-guide @ 20260520`)就行。
## Library 怎么扩
项目仓库自己(task_assistant 这类)用各自的 tag 方案(通常是 semver `vX.Y.Z`),写在项目自己的 `AGENTS.md` 里。
碰到跨项目的具体话题、塞进 AGENTS.md 会拖肿(比如"PII 处理"、"eval 报告格式"),就在 `library/<topic>/` 下写 `SPEC.md`。
具体命令和什么时候切 tag——见 [`AGENTS.md`](AGENTS.md) 的 Git workflow 节。
收录标准(同时满足):
## 几条最容易踩的线(速查)
1. 至少踩过两次
2. 比 AGENTS.md 通用规则窄
3. 步骤稳定到能写下来
完整版在 AGENTS.md 和 library/,这里挑人最常忘的:
- 长 session 的上下文会污染输出,新任务开新 session
- 不读 diff 就 "looks good" 是 bug 上线的标准姿势
- 一个 session 不要同时让 Claude Code 和 Codex 改同一个文件
- AI 试同一个方案两次报同样的错——叫停,自己上
- `git add .` 前先 `git status` 看一眼,确认没有不该传的文件
- 提交前 `git diff --cached` 扫一眼;密钥误提交的应急流程在 [`library/git-upload/SPEC.md`](library/git-upload/SPEC.md)
加一条要同时更新 [`library/README.md`](library/README.md) 的 catalog 表。
## 远端