diff --git a/AGENTS.md b/AGENTS.md index 7b16299..ca290ec 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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: +Why: +Done when: +Out of scope: +Risks: +``` -### 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 `/.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: ``` / -├── 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 — -> 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 - ## Run it - ```bash ``` ## Architecture - Key files: - `` — ## Conventions specific to this repo - ## 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 +(`/.claude/skills/`), plugin marketplace. -- **User skills** (`~/.claude/skills/`) — installed once, available - everywhere -- **Project skills** (`/.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: `/` — `bai/auth-retry`, - `bai/eval-agent-rerun`. Lowercase, hyphens, handle prefix. -- Long-lived integration: `integration/` — only by team agreement. + direct pushes. +- Feature branches: ``, lowercase, hyphenated. Project may + prefix with owner (`/`) — follow the project's existing + convention. - Delete branches after merge. ### Commits @@ -382,10 +331,8 @@ are hard to trace. ``` -- `` is a directory or component, lowercase: `eval-agent`, - `task_assistant`, `docs`, `git-workflow`. +- `` 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 ". -- 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: ``, with `-N` suffix for same-day reissues +(e.g. `-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 -m "team-guide : " +git push origin ``` Inspect: ```bash git tag --sort=-creatordate -git show 20260520 -git log --oneline 20260513..20260520 +git show +git log --oneline .. ``` 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: + Why: + Done when: + Out of scope: + Risks: + ``` -### 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. diff --git a/README.md b/README.md index 064e5b1..501f0d0 100644 --- a/README.md +++ b/README.md @@ -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 + └── /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//` 下写 `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 表。 ## 远端