Compare commits
4
Commits
20260520-4
...
20260521-3
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
161559a83d | ||
|
|
17671b2b22 | ||
|
|
c8ce92a2ed | ||
|
|
c5e6ebb534 |
No files matched your search
@@ -1,66 +1,86 @@
|
||||
# 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 里的内容,引用就行。
|
||||
|
||||
## 开新项目时丢给 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、`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 表。
|
||||
|
||||
## 远端
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
```
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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 天>内反馈给发送方
|
||||
@@ -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)。
|
||||
@@ -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 / 等等。>
|
||||
Reference in new issue
Block a user