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>
This commit is contained in:
阿白叔andClaude Opus 4.7 committed 2026-05-20 23:38:46 +08:00
1 parent 94eb7ef70a
commit f70c6e4d15
9 files changed
+514 -637

No files matched your search

+135 -302
View File
@@ -9,6 +9,21 @@ truth.
> Human-facing entry point: [`README.md`](README.md) (Chinese,
> condensed). When humans want the full ruleset, they read this file.
## How AI agents use this repo
Before starting non-trivial work in any team project, an agent should:
1. **Read this `AGENTS.md`** — general rules (vibe coding, Git, code
style, planning, handoff).
2. **Scan [`library/README.md`](library/README.md)** — focused specs
for narrower topics. Read the entries that match the current task.
3. **Read the project's own `AGENTS.md`** — project-specific stuff
(how to run it, architecture, project-only don'ts). Project AGENTS.md
files do **not** repeat team-guide content; they reference it.
In short: team-guide is the external rulebook every project's agent
reads at task start. Project AGENTS.md files stay small and specific.
## Project
This repo holds our team's working agreements. It is **documentation,
@@ -27,12 +42,9 @@ read the change and would have written the same."
## Language policy
- **Human-facing**: Chinese — `README.md` and the human-fillable
templates (`templates/README.md.template`,
`templates/PR_DESCRIPTION.template.md`,
`templates/HANDOFF_CHECKLIST.template.md`).
- **AI-facing**: English — this file, `CLAUDE.md`,
`templates/CLAUDE.md.template`, `templates/AGENTS.md.template`.
- **Human-facing**: Chinese — `README.md` only.
- **AI-facing**: English — this file, `CLAUDE.md`, anything under
`library/`.
- **Git metadata**: English — commit messages, PR titles, branch
names, tag annotations. AI tools and search work better on English.
@@ -172,7 +184,42 @@ In this order:
A new contributor (human or AI) should be productive after one read.
Past 100 lines, split — it's drifted into "documentation."
Use [`templates/AGENTS.md.template`](templates/AGENTS.md.template).
Skeleton to copy into a new project's `AGENTS.md`:
```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.
## Project
<one or two sentences>
## Run it
```bash
<install / run / test / lint commands>
```
## Architecture
<one paragraph: entry points, data flow, major modules>
Key files:
- `<path>` — <one-line role>
## Conventions specific to this repo
<naming patterns, where to add new features, what's auto-generated>
## Don'ts
- Don't <…>
```
`CLAUDE.md` in a new project is one line: `@AGENTS.md`.
### Permissions (Claude Code)
@@ -355,8 +402,11 @@ task_assistant: drop unused legacy export path
- One PR per topic. Can't describe in one sentence → multiple PRs.
- Title under 70 chars, same shape as commit summary.
- Description uses
[`templates/PR_DESCRIPTION.template.md`](templates/PR_DESCRIPTION.template.md).
- 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.
- First push of a feature branch uses `-u`.
- Open as draft once runnable. Review-as-you-go beats review-at-the-end.
@@ -388,30 +438,18 @@ Author follow-ups:
### Tagging
Two styles by project type:
Tags are dated: `YYYYMMDD`, with `-N` suffix for same-day reissues
(`20260520-2`). Tag from `main`.
| Project type | Tag format | Example | Tag from |
| ------------ | ------------------ | ------------------------ | -------- |
| Spec repo | `YYYYMMDD[-N]` | `20260520`, `20260520-2` | `main` |
| Product repo | `vX.Y.Z` | `v0.2.4` | `dev` |
Decide: would a "user" receive a versioned artifact from this project?
Yes → product. No → spec.
Universal:
Rules:
- Annotated only (`git tag -a`).
- Tag message summarizes what changed since the previous tag.
- Tags are immutable once pushed. Wrong tag → cut a new one.
- Don't tag on feature branches.
- Max one tag per day, use `-N` for same-day reissues.
Spec-repo specific: max one tag per day. Same-day reissues → `-N`
suffix.
Product-repo specific: see [Product project rules](#5-product-projects)
for the full ruleset (semver triplet, manifest, sync list).
Spec tag:
Cut a tag:
```bash
git checkout main && git pull --ff-only
@@ -419,14 +457,6 @@ git tag -a 20260520 -m "team-guide 20260520: bilingual policy"
git push origin 20260520
```
Product tag:
```bash
git checkout dev && git pull --ff-only <remote> dev
git tag -a v0.2.4 HEAD -m "<Project> V0.2.4"
git push <remote> v0.2.4
```
Inspect:
```bash
@@ -435,19 +465,20 @@ git show 20260520
git log --oneline 20260513..20260520
```
When to cut a spec-repo tag:
When to cut a tag:
- Docs changed in a way teammates need to re-read.
- A template was added, removed, or restructured.
- A new convention is now in effect (not just proposed).
- A library/ entry was added, removed, or restructured.
When **not** to cut a spec-repo tag:
When **not** to cut a tag:
- Typos, formatting, link fixes → just push to `main`.
- Drafts under discussion → use a PR.
Product tagging follows the release flow in
[Product projects](#5-product-projects).
Project repos in the workspace use their own tag schemes (typically
semver `vX.Y.Z`). Each project documents its own scheme in its own
`AGENTS.md`.
### Don'ts
@@ -537,8 +568,7 @@ Every repo has one. In order:
4. **Where does data come from / go to?** Only if non-obvious.
5. **Pointers.** Related repos, dashboards, docs.
Use [`templates/README.md.template`](templates/README.md.template).
Shorter than the template is fine — delete unused sections.
Shorter than this is fine — drop sections that don't apply.
### Don'ts
@@ -549,269 +579,22 @@ Shorter than the template is fine — delete unused sections.
---
## 5. Product projects
## 5. Team library
For projects that ship versioned artifacts to users (task_assistant,
authoring-tool, etc.). Spec repos (this one) ignore this section.
Narrower specs that don't fit cleanly in this file live under
[`library/`](library/). Catalog: [`library/README.md`](library/README.md).
### Spec vs product
When an agent picks up a task, it should scan the catalog after reading
this file and read entries that match. Each entry leads with a "When
to read this" section so the decision is fast.
| Dimension | Spec repo | Product repo |
| ------------------ | ---------------------------- | ------------------------------------- |
| Content | Docs, conventions, templates | Executable code, shippable artifacts |
| Tag format | `YYYYMMDD` / `YYYYMMDD-N` | `vX.Y.Z` |
| Acceptance | Human can read it | Tests pass, runs |
| Distribution | Git itself | Git (source) + dist channel (binaries)|
| Version-field sync | None | Multiple sites must agree |
| Users | Team members | Real end users |
Current entries:
Unsure? "Will a user receive a versioned artifact from this?" Yes → product.
- [`library/git-upload/`](library/git-upload/SPEC.md) — what to commit,
what not to, how to recover from leaked secrets.
### Versioning
Semver triplet: `major.minor.patch`.
- **major** — backward-incompatible (schema, CLI args, artifact format)
- **minor** — backward-compatible additions
- **patch** — bug fixes, perf, internal refactors
Three forms, **all must agree**:
| Use | Format | Example | Where |
| ----------- | --------- | --------- | ----------------------------------- |
| Internal | `X.Y.Z` | `0.2.4` | `package.json`, `pyproject.toml` |
| Display | `VX.Y.Z` | `V0.2.4` | UI chips, README title, release note|
| Git tag | `vX.Y.Z` | `v0.2.4` | Git tag |
Each product project lists its **release-bump checklist** in one place
(usually its own `AGENTS.md`). task_assistant's example:
```
package.json "version": "0.2.4"
public/index.html version chip default
server.js fallback version
scripts/build-release.js fallback + release notes
scripts/build-release-windows.js fallback + release notes
README.md title, version status
README.en.md same
```
Miss one → next release drifts.
### Tags (product)
- Annotated. Message: `<Project Name> V<x.y.z>`.
- One version, one tag — don't split across platforms.
- Already-shipped tags don't move. Wrong → ship a patch.
- Mistake before shipping (rare):
```bash
git tag -d v0.2.4
git push <remote> :refs/tags/v0.2.4
git tag -a v0.2.4 <correct-sha> -m "<Project> V0.2.4"
git push <remote> v0.2.4
```
### Branches
`dev` is the collaboration trunk. Feature branches off `dev`, PR back to
`dev`. Don't keep an unclear `master`. Stable branches use clear names:
`release/v0.3`, `release/v0.3-hotfix`.
### Git vs distribution channel
Git holds source. The distribution channel (OpenList, Hugging Face,
S3, etc.) holds artifacts. They don't mix.
Into Git:
- Source, build scripts, docs, conventions, small static assets,
templates, role/config tables.
Out of Git:
```
config/ local config
logs/ runtime logs
feedback-records/ user feedback
generated_task_packages/ task outputs
reports/ verification reports
runtime-temp/ transient state
release/ release-build/ release-dev/ release-merge/
.venv/ __pycache__/ node_modules/
```
Distribution channel layout (typical):
```
/<project>/dist/ release zips + manifest
/<project>/feedback/<machine-id>/ uploaded user feedback
```
Release zips are **self-contained**: user unzips, clicks, runs. No
dependency installs on user machines.
### Manifest
Top-level `manifest.json` in the dist channel — clients read it to
decide whether to update:
```json
{
"name": "<project-name>",
"version": "0.2.4",
"displayVersion": "V0.2.4",
"released_at": "2026-05-18T17:00:00Z",
"platforms": {
"windows": {
"url": "<dist-url>/<project>-v0.2.4-windows.zip",
"size": 123456789,
"sha256": "<hex>"
},
"macos-arm64": { "url": "...", "size": ..., "sha256": "..." },
"macos-x64": { "url": "...", "size": ..., "sha256": "..." }
},
"release_notes": "<short markdown>"
}
```
After upload, **re-fetch** the manifest and eyeball size + sha256.
Same size as previous → cache or upload error.
### Update flow (user-confirmed, not silent)
1. Client startup fetches manifest, compares versions.
2. New version → **prompt the user**, don't auto-download.
3. User confirms → download to local.
4. User confirms install → restart.
Never silently skip a step. This goes in every product's `AGENTS.md`
"Don'ts."
### Feedback & logs
Local-first, async upload:
```
local:
feedback-records/feedback-<timestamp>-<id>.json
logs/<project>-YYYY-MM-DD.jsonl
remote (after successful upload):
/<project>/feedback/<machine-id>/<feedback-file>.json
```
- Upload failure must not lose local data. UI says "saved locally,
upload failed, retry later."
- **Redact before send**: API keys, Bearer tokens, cookies, passwords,
secrets, private account info.
- Triage flow: ask users to use the feedback page, **not** to send raw
`config/` or full log directories.
### Sensitive-info scan
Pre-commit:
```bash
git diff --cached
```
Periodic keyword scan:
```bash
git grep -nE "sk-|hf_|Bearer |apiKey|ANTHROPIC_API_KEY|OPENAI_API_KEY|password|secret" \
-- ':!*.lock' ':!vendor/**' ':!**/__pycache__/**'
```
Hits require **human judgment** — demo keys in comments and real keys
both match. Don't blind-commit, don't blind-delete.
If a real secret was committed:
1. Invalidate the key/token immediately.
2. Replace local config.
3. Notify collaborators.
4. Decide whether to rewrite Git history (`git filter-repo` or team-agreed
tool).
A "delete the key" commit alone is **not safe** — history still has it.
### Standard release flow
```bash
# 1. Sync
git checkout dev
git pull --ff-only <remote> dev
git status --short --branch
# 2. Check
<lint command>
<test command>
# 3. Bump version (every site on the project's bump checklist)
# 4. Commit + tag
git add <files>
git commit -m "chore: release vX.Y.Z"
git tag -a vX.Y.Z HEAD -m "<Project> VX.Y.Z"
git push <remote> dev
git push <remote> vX.Y.Z
# 5. Build
<build command>
# 6. Upload manifest + zips, verify size/sha256
```
### Product README required sections
On top of the standard README sections, product projects add:
- **Version status** — current source version, internal version,
collaboration branch, repo URL, migration source (if any), default
local service URL (if any), default output dir.
- **Quick start** — per platform (Windows / macOS / Linux): unpack,
start, access, stop.
- **Bundle contents** — what's inside the release zip.
- **Release-bump checklist** — which files contain version strings to
update on release.
### Minimum delivery checklist
Every "ready to ship" version must have:
- [ ] `<remote>/dev` has the corresponding commit
- [ ] `<remote>` has the corresponding tag (`v<x.y.z>`)
- [ ] `package.json` / `pyproject.toml` version correct
- [ ] UI version chip displays correctly
- [ ] Lint / typecheck / test all pass
- [ ] Distribution channel manifest points at correct platform zips
- [ ] manifest size / sha256 match actual files
- [ ] Release zip unpacks → start script → runs
- [ ] Zip contains **no** API keys, logs, user feedback, generated
outputs, or verification reports
Any unchecked → not "ready to ship."
### What new product projects need
Beyond the standard `AGENTS.md` + `CLAUDE.md` + `.claude/`:
1. **`docs/COLLABORATION_AND_RELEASE_WORKFLOW.md`** (or similar) — a
project-specific specialization referencing this section, listing
the project's bump checklist, build commands, and dist paths.
task_assistant's is the reference example.
2. **`scripts/build-release.*`** — outputs zip + updates `manifest.json`.
3. **Bump checklist** — single source of truth in `AGENTS.md` or the
workflow doc above.
4. **`CHANGELOG.md`** — one entry per version, semver order, user-visible
changes.
YAGNI:
- Complex release tooling (Lerna, Changesets) — small team, manual is fine.
- Auto-generated release notes — good commit messages suffice.
- Multi-environment config systems — only when actually needed.
Promotion criteria, layout, and adding rules: see
[`library/README.md`](library/README.md).
---
@@ -876,9 +659,8 @@ Handoff is **part of the deliverable**, not afterthought packaging.
- **External** — versioned artifact to a partner / customer / downstream.
Zip, dataset, release.
Both use
[`templates/HANDOFF_CHECKLIST.template.md`](templates/HANDOFF_CHECKLIST.template.md).
External has higher bar.
Both use the [handoff checklist](#handoff-checklist) below. External has
higher bar.
### Task package layout
@@ -952,6 +734,57 @@ description → run test plan → form an opinion — **without messaging you.**
3. Note any surprise — naming, missing files, version mismatch — and
send back within a day. Drift gets worse with silence.
### Handoff checklist
Copy into the package (external handoff) or PR description (internal).
Fill it before declaring handoff done.
```markdown
## Identity
- Name:
- Version: <e.g. v0.5.0 or commit sha or tag>
- Generated at: <ISO timestamp>
- Source repo:
- Source commit: <full sha>
- Owner: <name>
- Recipient: <name or team>
## Contents
- [ ] README.md — what this is, how to use it
- [ ] CHANGELOG.md — diff vs previous version (or "first release")
- [ ] manifest.json — all fields filled or explicitly null
- [ ] VERIFICATION.md — what was checked, results
- [ ] Data / artifacts
- [ ] Scripts (only what's required to use the package)
## Verification
- [ ] Record / file counts match expected
- [ ] Checksums computed and recorded
- [ ] Sanity checks pass (list them)
- [ ] No secrets, .env, or credentials
- [ ] No PII unless explicitly part of deliverable
- [ ] Total size reasonable for delivery channel
## Reproducibility (external handoff only)
- [ ] Confirmed someone with repo access can rebuild from source_commit
- [ ] Build / generation command documented in README.md
- [ ] External dependencies pinned
## Provenance (if AI-assisted)
- Model used:
- Human-in-loop steps:
- Notable AI-assisted decisions:
## Known limitations
- <…>
## Recipient instructions
- [ ] Read README.md first
- [ ] Run verification report; if fails, stop and contact sender
- [ ] Confirm receipt within <X days>
- [ ] Report any surprises within <X days>
```
---
## Working directory expectations (this repo)
+42 -21
View File
@@ -5,16 +5,26 @@
完整规则在 [`AGENTS.md`](AGENTS.md)(英文,给 AI 看)——本仓库的**唯一规则来源**。
这份 README 是给人的导览,知道去哪查、怎么参与就行。
## 怎么用
## 这个仓库给谁用
**给 AI 用**。每个团队项目里 AI 开干前应该先读 team-guide:
1. 读 [`AGENTS.md`](AGENTS.md)——团队通用规则
2. 扫 [`library/README.md`](library/README.md)——按当前任务挑相关条目读
3. 再读项目自己的 `AGENTS.md`——只放项目特定的东西
项目自己的 `AGENTS.md` **不重复**这里的规则,引用就行,保持小而具体。
## 怎么用(人)
1. **新成员** —— 读这份 README 五分钟,再扫一眼 [AGENTS.md](AGENTS.md) 的目录。具体规则用到再翻。
2. **新项目** —— 从 [`templates/`](templates/) 复制对应模板。新仓库根目录放 `AGENTS.md`,再放一行 `@AGENTS.md` 的 `CLAUDE.md`,让 Claude Code 和 Codex 读同一份。
2. **新项目** —— 在新仓库根目录放 `AGENTS.md`(骨架在 [AGENTS.md](AGENTS.md) 的 Claude Code & Codex 节),再放一行 `@AGENTS.md` 的 `CLAUDE.md`。让两边 AI 工具读同一份项目说明。
3. **不同意某条规则** —— 在本仓库开 PR 改它,不要私下绕开。
## 语言策略
- **给人看的(中文)**:本 README、`templates/` 里给人填的(README、PR、handoff)。
- **给 AI 看的(英文)**:[`AGENTS.md`](AGENTS.md)、[`CLAUDE.md`](CLAUDE.md)、AI 专用模板。
- **给人看的(中文)**:本 README。
- **给 AI 看的(英文)**:[`AGENTS.md`](AGENTS.md)、[`CLAUDE.md`](CLAUDE.md)、`library/` 下所有内容。
- **Git 元数据(英文)**:commit、PR 标题、分支名、tag 注释。
理由:AI 工具和搜索更吃英文 metadata;规则只需要一份不需要两份;中文给人在入口处看到。
@@ -24,43 +34,54 @@
```
team-guide/
├── README.md ← 你正在看(中文,给人)
├── AGENTS.md ← 全部规则(英文,给 AI)
├── AGENTS.md ← 全部团队规则(英文,给 AI)
├── CLAUDE.md ← 一行 @AGENTS.md import
└── templates/ ← 新项目脚手架
└── library/ ← 窄主题专项规范目录
├── README.md ← catalog
└── git-upload/ ← 第一篇:什么该传什么不该传
└── SPEC.md
```
[`AGENTS.md`](AGENTS.md) 内含 7 大章:
项目背景与编辑规则 · Vibe coding · Claude Code & Codex 配置 ·
Git 工作流 · 代码与产出风格 · 产品类项目(semver、manifest、发版)·
规划节奏 · Handoff。
[`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 风格:
- **规范类**(本仓库 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。
本仓库(规范类)按日期打 tag:`YYYYMMDD`,比如 `20260520`。同一天多次发布加 `-N` 后缀(`20260520-2`)。从 `main` 打 tag。
通用规则:
- `main`(规范类)/ `dev`(产品类)永远是当前工作副本。
- `main` 永远是当前工作副本。
- 只用 annotated tag(`git tag -a`)。
- Tag 一旦推到远端就不能改、不能删、不能 force-push。错了切新的。
- 谁要"用某一版",告诉对方 tag 名(`team-guide @ 20260520`、`task_assistant @ v0.2.4`)就行。
- 谁要"用某一版",告诉对方 tag 名(`team-guide @ 20260520`)就行。
具体命令、什么时候切 tag、产品项目发版细则——见 [`AGENTS.md`](AGENTS.md) 的 Git workflow 和 Product projects 两节。
项目仓库自己(task_assistant 这类)用各自的 tag 方案(通常是 semver `vX.Y.Z`),写在项目自己的 `AGENTS.md` 里。
具体命令和什么时候切 tag——见 [`AGENTS.md`](AGENTS.md) 的 Git workflow 节。
## 几条最容易踩的线(速查)
完整版在 AGENTS.md,这里挑人最常忘的:
完整版在 AGENTS.md 和 library/,这里挑人最常忘的:
- 长 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
- `git add .` 前先 `git status` 看一眼,确认没有不该传的文件
- 提交前 `git diff --cached` 扫一眼;密钥误提交的应急流程在 [`library/git-upload/SPEC.md`](library/git-upload/SPEC.md)
## 远端
+50
View File
@@ -0,0 +1,50 @@
# 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 |
(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.
-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 / 等等。>