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:
1 parent
94eb7ef70a
commit
f70c6e4d15
9 files changed
+514
-637
No files matched your search
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
## 远端
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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