Author SHA1 Message Date
阿白叔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
10 changed files with 900 additions and 892 deletions

No files matched your search

+297 -539
View File
File diff suppressed because it is too large. Load diff
+27 -39
View File
@@ -1,66 +1,54 @@
# team-guide
我们小团队的 AI 协作(vibe coding)开发约定。1–3 人规模,规则不多但都是真踩过的坑。
我们小团队的 AI 协作开发约定。**给 AI 看的**——每个项目里 AI 开干前先读这里。
完整规则在 [`AGENTS.md`](AGENTS.md)(英文,给 AI 看)——本仓库的**唯一规则来源**。
这份 README 是给人的导览,知道去哪查、怎么参与就行。
完整规则在 [`AGENTS.md`](AGENTS.md)(英文)。这份 README 只是入口说明。
## 怎么用
## 这个仓库怎么用
1. **新成员** —— 读这份 README 五分钟,再扫一眼 [AGENTS.md](AGENTS.md) 的目录。具体规则用到再翻。
2. **新项目** —— 从 [`templates/`](templates/) 复制对应模板。新仓库根目录放 `AGENTS.md`,再放一行 `@AGENTS.md` 的 `CLAUDE.md`,让 Claude Code 和 Codex 读同一份。
3. **不同意某条规则** —— 在本仓库开 PR 改它,不要私下绕开。
AI 进任何团队项目前的读取顺序:
1. [`AGENTS.md`](AGENTS.md) —— 团队通用规则
2. [`library/README.md`](library/README.md) —— 按当前任务挑相关条目读
3. 项目自己的 `AGENTS.md` —— 只放项目特定的东西
项目自己的 `AGENTS.md` **不重复** team-guide 里的内容,引用就行。
## 语言策略
- **给人看的(中文)**:本 README、`templates/` 里给人填的(README、PR、handoff)。
- **给 AI 看的(英文)**:[`AGENTS.md`](AGENTS.md)、[`CLAUDE.md`](CLAUDE.md)、AI 专用模板。
- **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
└── templates/ ← 新项目脚手架
└── library/ ← 窄主题专项规范
├── README.md ← catalog
└── <topic>/SPEC.md
```
[`AGENTS.md`](AGENTS.md) 内含 7 大章:
项目背景与编辑规则 · Vibe coding · Claude Code & Codex 配置 ·
Git 工作流 · 代码与产出风格 · 产品类项目(semver、manifest、发版)·
规划节奏 · Handoff。
## 版本管理
按**项目类型**分两种 tag 风格:
本仓库按日期打 tag:`YYYYMMDD`(同一天多次发布加 `-N` 后缀)。tag 不可改、不可删、不可 force-push。
- **规范类**(本仓库 team-guide、其他规约文档)—— 按日期 `YYYYMMDD`,比如 `20260520`。同一天多次发布加 `-N` 后缀(`20260520-2`)。从 `main` 打 tag。
- **产品类**(task_assistant、authoring-tool 这种有版本、有发行包的)—— semver `vX.Y.Z`,比如 `v0.2.4`。三处版本号必须同步:内部 `0.2.4` / 显示 `V0.2.4` / tag `v0.2.4`。从 `dev` 打 tag。
具体规则见 [`AGENTS.md`](AGENTS.md) §3 Git workflow。项目仓库自己用各自的 tag 方案(通常 semver `vX.Y.Z`),写在项目的 `AGENTS.md` 里。
通用规则:
## Library 怎么扩
- `main`(规范类)/ `dev`(产品类)永远是当前工作副本。
- 只用 annotated tag(`git tag -a`)。
- Tag 一旦推到远端就不能改、不能删、不能 force-push。错了切新的。
- 谁要"用某一版",告诉对方 tag 名(`team-guide @ 20260520`、`task_assistant @ v0.2.4`)就行。
碰到跨项目的具体话题、塞进 AGENTS.md 会拖肿(比如"PII 处理"、"eval 报告格式"),就在 `library/<topic>/` 下写 `SPEC.md`。
具体命令、什么时候切 tag、产品项目发版细则——见 [`AGENTS.md`](AGENTS.md) 的 Git workflow 和 Product projects 两节。
收录标准(同时满足):
## 几条最容易踩的线(速查)
1. 至少踩过两次
2. 比 AGENTS.md 通用规则窄
3. 步骤稳定到能写下来
完整版在 AGENTS.md,这里挑人最常忘的:
- 长 session 的上下文会污染输出,新任务开新 session
- 不读 diff 就 "looks good" 是 bug 上线的标准姿势
- 一个 session 不要同时让 Claude Code 和 Codex 改同一个文件
- AI 试同一个方案两次报同样的错——叫停,自己上
- 改了 `CLAUDE.md` / `AGENTS.md` 一边,另一边要在同一个 PR 里同步(本仓库已经用 `@AGENTS.md` 解决了,新项目要注意)
- 提交前 `git diff --cached` 扫一眼,密钥误提交的应急流程在 AGENTS.md 的 Sensitive-info scan 节
- 产品发版"必改字段清单"漏一处下版就漂移——清单写进项目自己的 AGENTS.md
加一条要同时更新 [`library/README.md`](library/README.md) 的 catalog 表。
## 远端
+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.
```
-69
View File
@@ -1,69 +0,0 @@
# AGENTS.md — <project name>
<!--
Template. Copy into a new repo and fill the bracketed sections.
Sister file: CLAUDE.md (Claude Code reads that one). Keep them in sync.
Delete sections that don't apply. Keep total length under ~100 lines.
-->
## Project
<One or two sentences. What does it do, who is it for.>
## Run it
```bash
# install
<command>
# run
<command>
# test
<command>
# lint / typecheck
<command>
```
## Architecture
<One paragraph. Where are the entry points, how does data flow, what
are the major modules. Skip diagrams unless they save words.>
Key files:
- `<path>` — <one-line role>
- `<path>` — <one-line role>
## Conventions specific to this repo
<Anything that's not obvious from reading the code. Naming patterns,
where to add new features, what's auto-generated, etc.>
## Language policy
<If this project follows the team's bilingual policy, copy this:>
- Human-facing docs (README, `docs/*.md`, human-fillable templates) are
in Chinese.
- AI-facing files (`CLAUDE.md`, `AGENTS.md`, AI-only templates) are in
English.
- Commit messages, PR titles, branch names, tag annotations: English.
## Don'ts
<Things Codex / Claude / a new contributor has gotten wrong before.
One line each. Add to this list as you discover them.>
- Don't <…>
- Don't <…>
## External resources
<Links to dashboards, related repos, docs, ticket trackers.>
## Sync
When you edit this file, also update `CLAUDE.md` (and vice versa). The
two files describe the same project to different tools.
-69
View File
@@ -1,69 +0,0 @@
# CLAUDE.md — <project name>
<!--
Template. Copy into a new repo and fill the bracketed sections.
Sister file: AGENTS.md (Codex reads that one). Keep them in sync.
Delete sections that don't apply. Keep total length under ~100 lines.
-->
## Project
<One or two sentences. What does it do, who is it for.>
## Run it
```bash
# install
<command>
# run
<command>
# test
<command>
# lint / typecheck
<command>
```
## Architecture
<One paragraph. Where are the entry points, how does data flow, what
are the major modules. Skip diagrams unless they save words.>
Key files:
- `<path>` — <one-line role>
- `<path>` — <one-line role>
## Conventions specific to this repo
<Anything that's not obvious from reading the code. Naming patterns,
where to add new features, what's auto-generated, etc.>
## Language policy
<If this project follows the team's bilingual policy, copy this:>
- Human-facing docs (README, `docs/*.md`, human-fillable templates) are
in Chinese.
- AI-facing files (`CLAUDE.md`, `AGENTS.md`, AI-only templates) are in
English.
- Commit messages, PR titles, branch names, tag annotations: English.
## Don'ts
<Things Claude / Codex / a new contributor has gotten wrong before.
One line each. Add to this list as you discover them.>
- Don't <…>
- Don't <…>
## External resources
<Links to dashboards, related repos, docs, ticket trackers.>
## Sync
When you edit this file, also update `AGENTS.md` (and vice versa). The
two files describe the same project to different tools.
-65
View File
@@ -1,65 +0,0 @@
# Handoff 清单 — <包名或分支名>
<!--
交付前填完整。外部 handoff 一起放进包里;内部 handoff 放进 PR
description。正文中文,技术字段(commit hash、ISO 时间戳等)保留
英文格式。
-->
## 身份信息
- **名称**:<包名或分支名>
- **版本**:<比如 v0.5.0 或 commit sha 或 tag 比如 20260520>
- **生成时间**:<ISO 时间戳>
- **源仓库**:<url>
- **源 commit**:<full sha>
- **作者 / handoff owner**:<name>
- **接收方**:<name 或团队>
## 内容物
- [ ] `README.md` —— 这是什么、怎么用
- [ ] `CHANGELOG.md` —— 跟上一版的差异(首发就写"first release")
- [ ] `manifest.json` —— 机器可读元数据,所有字段都填了或显式 null
- [ ] `VERIFICATION.md` —— 检查了什么、结果如何
- [ ] 数据 / 产物 —— 真正的交付物
- [ ] 脚本 —— 仅限于使用本包必须的脚本
## 验证
- [ ] 记录数 / 文件数与预期一致
- [ ] Checksum 已计算并记录
- [ ] 合理性检查通过(列出来)
- [ ] 不含密钥、`.env`、credential
- [ ] 不含 PII(除非交付协议里就明确包含)
- [ ] 总大小在传输渠道可接受范围
验证报告路径:`<path>`
## 可重现性
- [ ] 已确认有源仓库访问的人能从 `source_commit` 重建产物(写明
谁测的、什么时候测的)
- [ ] 构建 / 生成命令写在 `README.md` 里
- [ ] 外部依赖锁版本
## 来源(AI 协助生成时填)
- 使用的模型:<比如 claude-opus-4-7、gpt-5-codex>
- 人工审核步骤:<人审 / 批准了哪些部分>
- 值得标注的 AI 决策:<半年后产物有问题时会想知道的事>
## 已知限制
<不能用的场景、未覆盖的边界、本版没赶上的后续。具体写。"在我机器
上能跑"不是限制——是发布前要修的问题。>
- <…>
- <…>
## 给接收方的说明
- [ ] 先读 `README.md`
- [ ] 跑验证报告 —— 不通过就停下来联系发送方
- [ ] <X 天>内确认收到
- [ ] 任何意外(缺文件、版本不对、命名异常)<X 天>内反馈给发送方
-49
View File
@@ -1,49 +0,0 @@
<!--
PR description 模板。标题写在 PR 标题栏,不在这里。
标题格式:<area>: <祈使句小结,70 字符以内>。英文。
正文中文。
-->
## Summary(小结)
<一句话说清这个 PR 干了什么。需要的话再加 1–3 条 bullet。>
- <bullet>
- <bullet>
## Why(为什么)
<动机。解决什么问题、落实什么决策、修哪个 bug。如果挂着 issue
或者之前的讨论,链上来。>
## What changed(改了什么)
<列出实际改动,跨多个区域时按区域分组。写事实就行——diff 是真相
来源,这只是地图。>
- `<文件或区域>` — <改动>
- `<文件或区域>` — <改动>
## Test plan(测试方案)
<勾选式 checklist。做了的勾 `[x]`,没做的留 `[ ]` 并在下面解释为什么。
诚实——"没测"可以接受,"声称测了但没测"不行。>
- [ ] 单元测试本地通过(`<command>`)
- [ ] Lint / typecheck 通过(`<command>`)
- [ ] <功能特定的检查>
- [ ] <功能特定的检查>
## Out of scope(范围外)
<你注意到但**显式选择不在这个 PR 修**的东西。帮 reviewer 不要在这些
点上提出来。>
## Notes for reviewer(给 reviewer 的提示)
<让你意外的地方、值得标注的 AI 协作决策、走过的捷径,或者"我考虑
过 X 但选了 Y 因为 Z"。没什么可写就删掉这一节。>
---
🤖 AI 协助完成(Claude Code / Codex)。
-62
View File
@@ -1,62 +0,0 @@
# <项目名>
<一句话。这是什么,用大白话写。>
## 这玩意儿干啥的
<一段话。比 tagline 多点细节。谁会用、解决什么问题、明确**不**做
什么。>
## 快速上手
```bash
# clone
git clone <url>
cd <repo>
# 安装
<command>
# 跑起来
<command>
```
预期输出:
```
<几行用户应该看到的内容>
```
## 开发
```bash
# 测试
<command>
# lint / typecheck
<command>
# 格式化
<command>
```
代码在 `<dir>`。测试在 `<dir>`。架构细节看 [docs/](docs/)(没有就
删掉这行)。
## 配置
<env var、配置文件、密钥。指向 `.env.example` 如果有的话。不写真实
值。>
## 数据来源 / 流向
<仅当不显然时写。输入从哪来,输出到哪去。>
## 相关链接
- <链接>
- <链接>
## License
<Internal / MIT / 等等。>