diff --git a/AGENTS.md b/AGENTS.md index 067f194..7b16299 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 — + +> 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 + + + +## Run it + +```bash + +``` + +## Architecture + + + +Key files: +- `` — + +## Conventions specific to this repo + + + +## 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 dev -git tag -a v0.2.4 HEAD -m " V0.2.4" -git push 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: ` V`. -- 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 :refs/tags/v0.2.4 -git tag -a v0.2.4 -m " V0.2.4" -git push 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): - -``` -//dist/ release zips + manifest -//feedback// 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": "", - "version": "0.2.4", - "displayVersion": "V0.2.4", - "released_at": "2026-05-18T17:00:00Z", - "platforms": { - "windows": { - "url": "/-v0.2.4-windows.zip", - "size": 123456789, - "sha256": "" - }, - "macos-arm64": { "url": "...", "size": ..., "sha256": "..." }, - "macos-x64": { "url": "...", "size": ..., "sha256": "..." } - }, - "release_notes": "" -} -``` - -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--.json - logs/-YYYY-MM-DD.jsonl - -remote (after successful upload): - //feedback//.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 dev -git status --short --branch - -# 2. Check - - - -# 3. Bump version (every site on the project's bump checklist) - -# 4. Commit + tag -git add -git commit -m "chore: release vX.Y.Z" -git tag -a vX.Y.Z HEAD -m " VX.Y.Z" -git push dev -git push vX.Y.Z - -# 5. Build - - -# 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: - -- [ ] `/dev` has the corresponding commit -- [ ] `` has the corresponding tag (`v`) -- [ ] `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: +- Generated at: +- Source repo: +- Source commit: +- Owner: +- Recipient: + +## 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 +- [ ] Report any surprises within +``` + --- ## Working directory expectations (this repo) diff --git a/README.md b/README.md index acbfbc3..064e5b1 100644 --- a/README.md +++ b/README.md @@ -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) ## 远端 diff --git a/library/README.md b/library/README.md new file mode 100644 index 0000000..f1e8922 --- /dev/null +++ b/library/README.md @@ -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// +└── 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. diff --git a/library/git-upload/SPEC.md b/library/git-upload/SPEC.md new file mode 100644 index 0000000..9acf4a6 --- /dev/null +++ b/library/git-upload/SPEC.md @@ -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 `~/.` 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 ` 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 # 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. diff --git a/templates/AGENTS.md.template b/templates/AGENTS.md.template deleted file mode 100644 index e72fe2b..0000000 --- a/templates/AGENTS.md.template +++ /dev/null @@ -1,69 +0,0 @@ -# AGENTS.md — - - - -## Project - - - -## Run it - -```bash -# install - - -# run - - -# test - - -# lint / typecheck - -``` - -## Architecture - - - -Key files: - -- `` — -- `` — - -## Conventions specific to this repo - - - -## Language policy - - - -- 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 - - - -- Don't <…> -- Don't <…> - -## External resources - - - -## Sync - -When you edit this file, also update `CLAUDE.md` (and vice versa). The -two files describe the same project to different tools. diff --git a/templates/CLAUDE.md.template b/templates/CLAUDE.md.template deleted file mode 100644 index fa397dc..0000000 --- a/templates/CLAUDE.md.template +++ /dev/null @@ -1,69 +0,0 @@ -# CLAUDE.md — - - - -## Project - - - -## Run it - -```bash -# install - - -# run - - -# test - - -# lint / typecheck - -``` - -## Architecture - - - -Key files: - -- `` — -- `` — - -## Conventions specific to this repo - - - -## Language policy - - - -- 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 - - - -- Don't <…> -- Don't <…> - -## External resources - - - -## Sync - -When you edit this file, also update `AGENTS.md` (and vice versa). The -two files describe the same project to different tools. diff --git a/templates/HANDOFF_CHECKLIST.template.md b/templates/HANDOFF_CHECKLIST.template.md deleted file mode 100644 index 351a8f7..0000000 --- a/templates/HANDOFF_CHECKLIST.template.md +++ /dev/null @@ -1,65 +0,0 @@ -# Handoff 清单 — <包名或分支名> - - - -## 身份信息 - -- **名称**:<包名或分支名> -- **版本**:<比如 v0.5.0 或 commit sha 或 tag 比如 20260520> -- **生成时间**: -- **源仓库**: -- **源 commit**: -- **作者 / handoff owner**: -- **接收方**: - -## 内容物 - -- [ ] `README.md` —— 这是什么、怎么用 -- [ ] `CHANGELOG.md` —— 跟上一版的差异(首发就写"first release") -- [ ] `manifest.json` —— 机器可读元数据,所有字段都填了或显式 null -- [ ] `VERIFICATION.md` —— 检查了什么、结果如何 -- [ ] 数据 / 产物 —— 真正的交付物 -- [ ] 脚本 —— 仅限于使用本包必须的脚本 - -## 验证 - -- [ ] 记录数 / 文件数与预期一致 -- [ ] Checksum 已计算并记录 -- [ ] 合理性检查通过(列出来) -- [ ] 不含密钥、`.env`、credential -- [ ] 不含 PII(除非交付协议里就明确包含) -- [ ] 总大小在传输渠道可接受范围 - -验证报告路径:`` - -## 可重现性 - -- [ ] 已确认有源仓库访问的人能从 `source_commit` 重建产物(写明 - 谁测的、什么时候测的) -- [ ] 构建 / 生成命令写在 `README.md` 里 -- [ ] 外部依赖锁版本 - -## 来源(AI 协助生成时填) - -- 使用的模型:<比如 claude-opus-4-7、gpt-5-codex> -- 人工审核步骤:<人审 / 批准了哪些部分> -- 值得标注的 AI 决策:<半年后产物有问题时会想知道的事> - -## 已知限制 - -<不能用的场景、未覆盖的边界、本版没赶上的后续。具体写。"在我机器 -上能跑"不是限制——是发布前要修的问题。> - -- <…> -- <…> - -## 给接收方的说明 - -- [ ] 先读 `README.md` -- [ ] 跑验证报告 —— 不通过就停下来联系发送方 -- [ ] 内确认收到 -- [ ] 任何意外(缺文件、版本不对、命名异常)内反馈给发送方 diff --git a/templates/PR_DESCRIPTION.template.md b/templates/PR_DESCRIPTION.template.md deleted file mode 100644 index b0e6d16..0000000 --- a/templates/PR_DESCRIPTION.template.md +++ /dev/null @@ -1,49 +0,0 @@ - - -## Summary(小结) - -<一句话说清这个 PR 干了什么。需要的话再加 1–3 条 bullet。> - -- -- - -## Why(为什么) - -<动机。解决什么问题、落实什么决策、修哪个 bug。如果挂着 issue -或者之前的讨论,链上来。> - -## What changed(改了什么) - -<列出实际改动,跨多个区域时按区域分组。写事实就行——diff 是真相 -来源,这只是地图。> - -- `<文件或区域>` — <改动> -- `<文件或区域>` — <改动> - -## Test plan(测试方案) - -<勾选式 checklist。做了的勾 `[x]`,没做的留 `[ ]` 并在下面解释为什么。 -诚实——"没测"可以接受,"声称测了但没测"不行。> - -- [ ] 单元测试本地通过(``) -- [ ] Lint / typecheck 通过(``) -- [ ] <功能特定的检查> -- [ ] <功能特定的检查> - -## Out of scope(范围外) - -<你注意到但**显式选择不在这个 PR 修**的东西。帮 reviewer 不要在这些 -点上提出来。> - -## Notes for reviewer(给 reviewer 的提示) - -<让你意外的地方、值得标注的 AI 协作决策、走过的捷径,或者"我考虑 -过 X 但选了 Y 因为 Z"。没什么可写就删掉这一节。> - ---- - -🤖 AI 协助完成(Claude Code / Codex)。 diff --git a/templates/README.md.template b/templates/README.md.template deleted file mode 100644 index 9c03cc4..0000000 --- a/templates/README.md.template +++ /dev/null @@ -1,62 +0,0 @@ -# <项目名> - -<一句话。这是什么,用大白话写。> - -## 这玩意儿干啥的 - -<一段话。比 tagline 多点细节。谁会用、解决什么问题、明确**不**做 -什么。> - -## 快速上手 - -```bash -# clone -git clone -cd - -# 安装 - - -# 跑起来 - -``` - -预期输出: - -``` -<几行用户应该看到的内容> -``` - -## 开发 - -```bash -# 测试 - - -# lint / typecheck - - -# 格式化 - -``` - -代码在 ``。测试在 ``。架构细节看 [docs/](docs/)(没有就 -删掉这行)。 - -## 配置 - - - -## 数据来源 / 流向 - -<仅当不显然时写。输入从哪来,输出到哪去。> - -## 相关链接 - -- <链接> -- <链接> - -## License - -