diff --git a/AGENTS.md b/AGENTS.md index 9f852cd..067f194 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,103 +1,962 @@ # AGENTS.md — team-guide -Context for AI coding agents (Codex CLI, Codex in IDEs, other -AGENTS.md-aware tools) working in this repository. +Working agreements for our 1–3 person AI-assisted development team. +This is the canonical spec for AI coding agents (Claude Code, Codex, +and any other `AGENTS.md`-aware tool). Claude Code reads this via +`CLAUDE.md`'s `@AGENTS.md` import, so there's exactly one source of +truth. -> Sister file: `CLAUDE.md` (read by Claude Code). The two files cover -> the same ground — keep them in sync. Whichever tool runs reads its -> own file. +> Human-facing entry point: [`README.md`](README.md) (Chinese, +> condensed). When humans want the full ruleset, they read this file. ## Project -This repo holds our team's working agreements (1–3 person team, -AI-assisted "vibe coding" development). It is **documentation, not code**. -There is no build, test, or lint step. Acceptance is "a human can read -the change and would have written the same." +This repo holds our team's working agreements. It is **documentation, +not code** — no build, test, or lint step. Acceptance is "a human can +read the change and would have written the same." -## Editing rules - -When editing files in this repo: +## Editing rules (this repo) - One rule per bullet. If a rule needs a paragraph of justification, - split the rule out and put the justification on a `**Why:**` line. + split the rule out and put the reason on a `**Why:**` line. - Lead with the rule, then `**Why:**`, then `**How to apply:**` only - when non-obvious. Skip them when the rule speaks for itself. + when the rule isn't self-evident. - No emoji. No decorative headers. No "🚀 Getting started!" energy. -- Keep each doc under ~150 lines. Past that, split. -- Examples beat prose. A 3-line code block beats a paragraph of - description. +- Keep AGENTS.md under ~800 lines. Past that, split. +- Examples beat prose. A 3-line code block beats a paragraph. ## Language policy -- **Human-facing**: Chinese. `README.md`, `docs/*.md`, and the - human-fillable templates (`templates/README.md.template`, +- **Human-facing**: Chinese — `README.md` and the human-fillable + templates (`templates/README.md.template`, `templates/PR_DESCRIPTION.template.md`, - `templates/HANDOFF_CHECKLIST.template.md`) are in Chinese. -- **AI-facing**: English. `CLAUDE.md`, `AGENTS.md`, - `templates/CLAUDE.md.template`, `templates/AGENTS.md.template`, and - `docs/07-codex.md`'s code blocks / examples are in English. -- **Commit messages, PR titles, branch names, tag annotations**: English. - AI tools and search work better on English Git metadata. + `templates/HANDOFF_CHECKLIST.template.md`). +- **AI-facing**: English — this file, `CLAUDE.md`, + `templates/CLAUDE.md.template`, `templates/AGENTS.md.template`. +- **Git metadata**: English — commit messages, PR titles, branch + names, tag annotations. AI tools and search work better on English. -If you're an agent and you're about to write Chinese into a file the -human would never read, stop — you have the wrong file. +If you're an agent about to write Chinese into a file the human would +never read (or English into a file only humans read), stop — wrong file. -## What goes where +## CLAUDE.md and AGENTS.md sync -| Topic | File | -| ---------------------------------------------- | --------------------------------- | -| Human + AI work split | `docs/01-vibe-coding.md` | -| Claude Code config (CLAUDE.md, hooks, memory) | `docs/02-claude-code.md` | -| Branches, commits, PRs, tagging | `docs/03-git-workflow.md` | -| Skill catalog, planning cadence | `docs/04-skills-and-planning.md` | -| Naming, comments, code style | `docs/05-code-style.md` | -| Task packages, handoff checklists | `docs/06-handoff.md` | -| Codex usage and AGENTS.md conventions | `docs/07-codex.md` | -| Product project spec (semver, manifest, build) | `docs/08-product-spec.md` | +Claude Code reads `CLAUDE.md`; Codex and other agents read `AGENTS.md`. +In this repo, `CLAUDE.md` is a single line: `@AGENTS.md`. That makes +this file the only spec; both tools see the same content. -## What NOT to do +For other projects in our workspace where the two files are physical +copies (legacy or tool-mismatch reasons), the rules are: -- Don't add a doc for a rule we've used once. Wait until it's bitten - twice — then write it. -- Don't write process for processes' sake. If nobody would read or - follow it, don't write it. -- Don't quote external sources at length (license / copyright). Link - instead. -- Don't translate `CLAUDE.md` / `AGENTS.md` into Chinese. They're for - AI tools. -- Don't translate Chinese docs into English "for completeness." Pick - one language per file and stick with it. +- Bodies must stay in sync. Drift breaks one of the tools silently. +- Whoever edits one updates the other in the same PR. Add "Synced + AGENTS.md" (or "Synced CLAUDE.md") to the PR description. +- Reviewer blocks PRs that only touch one side. -## Commits +When starting a new project, prefer the single-file approach: write +`AGENTS.md`, make `CLAUDE.md` a one-line `@AGENTS.md` import. -- Format: `: `. Examples: - `git-workflow: clarify branch naming`, `docs: add Codex section`. -- One topic per commit. "and" in the summary means split it. -- Always include the `Co-Authored-By` trailer when AI-assisted. +--- -## Versioning / releases +## 1. Vibe coding — humans + AI work split -Two tag styles, by project type: +### The premise -- **Spec repos** (this one, other agreement docs) — date tags: - `YYYYMMDD`, with `-N` suffix for same-day reissues (`20260520-2`). - Tag from `main`. -- **Product repos** (task_assistant, authoring-tool — anything with - versioned artifacts shipped to users) — semver: `v`. Tag from - `dev`. Internal version (`0.2.4`), display version (`V0.2.4`), and - tag (`v0.2.4`) must stay in sync. See `docs/08-product-spec.md` for - the full ruleset (manifest, release-field sync list, sensitive-info - scan, minimum delivery checklist). +Claude / Codex write most of the code. Humans steer: framing problems, +making decisions, deciding what's good enough. We're not racing the AI +— we're skipping typing so we spend more time thinking. -Universal rules: +### The split -- Annotated tags only. Tag messages summarize what changed. -- Tags are immutable once pushed. If a tag is wrong, cut a new one. -- This repo is a spec repo, so tagging here means a date tag. +**AI does:** -## Working directory expectations +- Read code and explain it +- Write first-pass implementations against a clear spec +- Mechanical refactors (renames, extractions, type changes) +- Run tests, builds, linters; iterate on errors +- Generate boilerplate (configs, fixtures, CRUD) +- Search across the workspace and summarize -- The repo is small (10–20 files). You can `Read` everything before - acting; you don't need to spawn a sub-agent for exploration. -- Do not introduce `package.json`, `Makefile`, CI configs, or other +**Humans do:** + +- Decide what to build and why +- Frame the spec before AI touches code +- Approve any change with non-local consequences (deps, schema, infra, + auth, secrets) +- Read every diff before merging +- Make the call when AI has tried twice and is going in circles +- Sign off on commit messages and PR descriptions (AI drafts; you sign) + +If a task feels like it's drifting toward "AI decides", stop and write +a spec yourself first. + +### Prompt habits + +- **Frame, don't dictate.** Tell AI the goal, the constraints, and what + you've ruled out. Don't prescribe steps unless the steps are the point. +- **Name the file.** "Fix the bug in `eval-agent/runner.py`" beats "fix + the bug." Save AI a search. +- **Say what done looks like.** "Tests pass and the new flag defaults + to off" — measurable. "Make it cleaner" — not. +- **One task per turn.** Three unrelated asks → three messages or three + sessions. +- **Push back on bad output.** If the diff is wrong, say so plainly and + point at what's wrong. Don't accept code you wouldn't write yourself. + +### When to take over + +Stop letting AI drive when: + +- It's failed the same approach twice and the error is unchanged. +- It's adding "safety" code the task didn't ask for. +- The diff has grown past what you can read in one sitting. +- You can't explain the change to a teammate without re-reading the diff. +- It's about to do something irreversible — confirm explicitly. + +When you take over, write *why* in the PR description so the next person +doesn't repeat the loop. + +### Verifying AI output + +Treat every AI diff like a fast junior's PR: + +1. Does it build? +2. Do tests pass — and do new tests actually test the new code? +3. Did it touch files outside the stated scope? Look at every one. +4. Did it add deps? Check the lockfile diff. +5. Read every comment AI added. Half are noise — delete those. +6. Run user-facing features end-to-end. Type checks ≠ working software. + +### Anti-patterns + +- **Snowballing context.** Long sessions accumulate stale assumptions. + New task → new session. +- **Approval-by-default.** "Looks good" without reading the diff is how + bugs ship. +- **Outsourcing the spec.** "Figure out what we should do" is avoidance, + not a prompt. +- **Letting AI rewrite history.** If AI wants to refactor unrelated code + "while we're here", say no. Open a separate task. + +--- + +## 2. Claude Code & Codex configuration + +### Per-project files + +``` +/ +├── AGENTS.md ← canonical spec, committed +├── CLAUDE.md ← committed, single line: @AGENTS.md +└── .claude/ + ├── settings.json ← shared settings, committed + ├── settings.local.json ← personal overrides, gitignored + └── skills/ ← project skills, committed +``` + +`settings.local.json` is **always** gitignored — personal API keys, +local paths, individual hook tweaks. + +### AGENTS.md content per project + +In this order: + +1. **Project** — two sentences max. +2. **Run it** — build, test, lint as bash blocks. +3. **Architecture** — one paragraph. Entry points and data flow. No + diagrams unless they save words. +4. **Conventions specific to this repo** — naming, layout, patterns + that aren't obvious from the code. +5. **Don'ts** — things AI has gotten wrong before. One line each. + +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). + +### Permissions (Claude Code) + +Default: prompt for risky, allow read-only freely. + +In `.claude/settings.json`, allow without prompting: + +- All `Read`, `Glob`, `Grep` +- `Bash(git status)`, `Bash(git diff)`, `Bash(git log)`, + `Bash(git branch)` +- Project-specific read-only commands (`Bash(npm test)`, `Bash(pytest)`) + +Always prompt for: + +- `Edit` / `Write` outside the working tree +- `Bash` with destructive verbs (`rm`, `mv`, `git push`, + `git reset --hard`, package installs) +- Any MCP tool that talks to a remote service + +Approving the same prompt repeatedly → run the +`fewer-permission-prompts` skill to propose an allowlist from your +transcripts. + +### Codex approval & sandbox + +- **Approval**: default `on-request` (asks before commands). Use + `on-failure` or `never` only on personal, low-risk machines. + Production / shared / unfamiliar repos → keep `on-request`. +- **Sandbox**: default `workspace-write` + network off. Toggle network + on temporarily to install packages or fetch resources, then off. + `danger-full-access` rarely. +- Personal Codex preferences in `~/.codex/config.toml` — never commit. + +### Hooks + +Hooks enforce rules automatically. AI **does not reliably remember** +"from now on do X" across sessions; hooks do. + +Use hooks for: + +- Auto-formatting on file edit (Prettier, ruff, gofmt) +- Blocking edits to protected paths (`.env`, generated files, `dist/`) +- Auto-running tests after writing to a known test path +- Notifying on session stop / long-task completion + +Don't use hooks for: + +- One-off checks ("just remember X this week") +- Anything that depends on AI judgment + +Configure via `update-config` skill or edit `.claude/settings.json` +directly. One-line comment per hook. + +### Memory + +Per-machine memory system. Use it for: + +- **User**: who you are, role, preferences. +- **Feedback**: corrections that should stick across sessions, with + the *why*. +- **Project**: facts about ongoing work that aren't in the code + (deadlines, stakeholder decisions, why a refactor is happening). +- **Reference**: pointers to external resources (Linear, Grafana, + internal wikis). + +Don't put memory content in `AGENTS.md`. AGENTS.md is shared with the +team; memory is personal, per-machine, outside the repo. Don't use +memory as a notes app — task-scoped state goes in plans or PR descriptions. + +### Skills + +Skills live in three places: + +- **User skills** (`~/.claude/skills/`) — installed once, available + everywhere +- **Project skills** (`/.claude/skills/`) — committed, team-shared +- **Plugin skills** — installed via marketplace + +Promote a workflow to a skill when **all three** are true: + +1. Done it the same way three times. +2. Steps stable enough to write down. +3. Someone else would do it the same way given the spec. + +Only two true → leave it as a prompt snippet. + +Skill design: + +- One skill, one job. Branching skills are two skills. +- Verb-phrase names: `review-pr`, `cut-release`, `rebuild-fixtures` — + not `pr-helper`. +- Description (the line the model sees) says **when to invoke**, not + what the skill does. +- `SKILL.md` under 200 lines; long skills split into stages. +- Examples beat instructions. + +Recommended installs: + +``` +anthropic-skills:consolidate-memory periodic memory cleanup +simplify review changed code for reuse/quality +fewer-permission-prompts propose allowlist from transcripts +review review a pull request +security-review security pass on pending changes +``` + +Review skills like PRs — read, run once on a real task, merge. Skills +nobody runs after a month → archive (`.claude/skills/_archive/`). + +### Sub-agents + +Spawn a sub-agent (Claude `Agent` tool) when: + +- Task needs cross-file search and you don't want results in main context. +- You want a second independent read on a design or diff. +- Work is genuinely parallel (e.g. researching three options). + +Don't spawn for tasks the main agent can do in two tool calls. + +### Sessions + +- One task per session. New task → new session. +- Long session, context bar filling → finish current step, summarize + into a plan or PR draft, start fresh. +- Don't `--continue` yesterday's session for a new topic. Stale context + leaks in. + +### Tool selection (mixing Claude Code + Codex) + +Both fine; mild preferences: + +- **Writing docs / specs** — Claude Code (this repo was written that way). +- **Large refactors / cross-file features** — Claude Code (plan mode + + sub-agents). +- **Narrow edits, run a test, change a config** — Codex CLI (faster + startup). +- **In-IDE inline edits** — Codex IDE plugin or Cursor. + +Don't run two tools editing the same file simultaneously — overwrites +are hard to trace. + +--- + +## 3. Git workflow + +### Branches + +- `main` (spec repos) / `dev` (product repos) is always shippable. No + direct pushes, no exceptions. +- Feature branches: `/` — `bai/auth-retry`, + `bai/eval-agent-rerun`. Lowercase, hyphens, handle prefix. +- Long-lived integration: `integration/` — only by team agreement. +- Delete branches after merge. + +### Commits + +``` +: + + +``` + +- `` is a directory or component, lowercase: `eval-agent`, + `task_assistant`, `docs`, `git-workflow`. +- Imperative: "add", "fix", "rename" — not "added" / "adding". +- Body wraps at ~72 chars. Skip it for trivial commits. +- One topic per commit. "and" in the summary → split. +- Always include `Co-Authored-By` for AI-assisted commits. +- English. + +Examples: + +``` +eval-agent: rerun failed tasks with stable seed +docs: clarify branch naming +task_assistant: drop unused legacy export path +``` + +### Pull requests + +- 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). +- First push of a feature branch uses `-u`. +- Open as draft once runnable. Review-as-you-go beats review-at-the-end. + +### Review + +Every PR reviewed before merge — own AI-assisted PRs included. + +Reviewer: + +1. Description matches diff? Surprises → ask. +2. Read every changed file. Off-topic file → ask why it's in this PR. +3. Run locally if not obviously correct from reading. +4. New deps, schema changes, env vars, auth-touching code → block until + justified. +5. Comment on least-important issue first; merge-blocker last so it's + clearly the gate. + +Author follow-ups: + +- Address every comment, even with "agreed, fixed in ". +- Disagree → push back in writing. Don't silently ignore. +- Squash fixup commits before merge if history is noisy. + +### Merging + +- Squash for feature branches. Merge commits reserved for integration. +- Final squash message follows commit format. +- Delete the branch on merge. + +### Tagging + +Two styles by project type: + +| 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: + +- 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. + +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: + +```bash +git checkout main && git pull --ff-only +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 +git tag --sort=-creatordate +git show 20260520 +git log --oneline 20260513..20260520 +``` + +When to cut a spec-repo 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). + +When **not** to cut a spec-repo 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). + +### Don'ts + +- No `git push --force` to `main`. Period. To your own branch only if + certain nobody pulled it. +- No `--no-verify` to skip hooks. Fix what the hook reports. +- No amending pushed commits. Add a new commit instead. +- No deleting or moving pushed tags. Cut a new one. +- No committing `.env`, secrets, or files >5 MB without a Git LFS + conversation. +- No `git add .` / `git add -A` when there are unrecognized untracked + files. Stage by name. + +--- + +## 4. Code & deliverable style + +### Naming + +- **Files** — lowercase. Docs hyphenated (`git-workflow.md`), Python + underscored (`task_runner.py`), JS/TS kebab where ecosystem prefers. + Match the surrounding project. +- **Functions** — verb phrases. `loadConfig`, not `config`. `runTask`, + not `taskRunner`. +- **Variables** — what they are, not their type. `users`, not + `userArray`. `retryCount`, not `n`. +- **Booleans** — `is*`, `has*`, `should*`. `isReady`, not `ready`. +- **Constants** — `UPPER_SNAKE_CASE` only at module level. Inside + functions, plain `const`. +- **No abbreviations** unless they're domain terms. `database`, not + `db`. (`req`/`res` in Express is fine.) + +### Comments + +Default: none. Justified when **all** are true: + +- *Why* is non-obvious from code. +- A future reader would otherwise misread. +- The code can't be made clearer (rename / extract / restructure). + +Don't write: + +- `// increment counter` next to `counter++` +- `// added for the auth refactor` — belongs in the commit message +- Block comments restating signatures +- TODOs without owner or date + +Do write: + +- One-liners for non-obvious workarounds, with the *why*. +- `# NOTE:` for behavior that would surprise a reader. +- Module headers when the file does something the layout doesn't explain. + +### File structure + +- One concept per file. Can't summarize in one sentence → split. +- Tests next to the code unless project already uses parallel test trees. +- Generated files in `dist/`, `build/`, etc. — and `.gitignore`. Never + edit a generated file. +- Lockfiles always checked in. + +### Errors + +- Fail loudly at boundaries (user input, external APIs, file I/O). +- Don't `try/except` to silence. Catch → handle. +- Internal functions trust callers. Don't validate the same input three + layers deep. +- Logged errors include enough context to debug from logs alone. + +### Tests + +- Test behavior, not implementation. Behavior-preserving refactor that + breaks a test → test was wrong. +- One assertion per test ideally. +- Fixtures next to the tests using them. +- Slow / flaky tests get marked or quarantined, not silently retried. +- New code without a test is incomplete unless project has no test + infrastructure (rare, and a bug itself). + +### READMEs + +Every repo has one. In order: + +1. **What is this?** One paragraph. +2. **How do I run it?** Bash blocks. +3. **How do I develop on it?** Code layout, conventions. +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. + +### Don'ts + +- No third way to do something we already do two ways. +- No config options "for flexibility" without a real use case. YAGNI. +- No unrelated refactors in a feature PR. Open a separate one. +- No optimization before measurement. + +--- + +## 5. Product projects + +For projects that ship versioned artifacts to users (task_assistant, +authoring-tool, etc.). Spec repos (this one) ignore this section. + +### Spec vs product + +| 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 | + +Unsure? "Will a user receive a versioned artifact from this?" Yes → product. + +### 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. + +--- + +## 6. Planning cadence + +1–3 person team. Lightest process that keeps us aligned. + +### Weekly + +- Async written sync (Monday morning). Each person posts: + 1. What I shipped last week (one line per item). + 2. What I'm picking up this week (one line per item). + 3. What's blocked or unclear (the only section worth reading carefully). +- 30-minute live call mid-week. Agenda is the "blocked or unclear" lines. + +### Per task + +Before starting work that takes more than ~half a day: + +1. Write a 5-line spec: *Goal / Why / Done when / Out of scope / Risks*. +2. Drop in PR description (draft PR fine) **before** writing code. +3. If AI does most of the typing, the spec is also the prompt. + +After: + +1. PR description matches what shipped. +2. Lessons future-you would want → Claude memory (feedback / project + types). See [Memory](#memory). + +### Quarterly + +Half a day to: + +- Re-read this `AGENTS.md`. Open PRs for what's stale. +- Review skill catalog. Archive unused. +- Run `consolidate-memory` on personal memory files. + +### What planning is *not* + +- Not Jira tickets. Two people don't need a board. +- Not Gantt charts. Need one → building the wrong thing. +- Not status theater. Monday post is for spotting blocks, not proving + you worked. + +--- + +## 7. Handoff + +Task packages, deliverables, work transfers between team members or to +external consumers. + +### Why this matters + +Handoff failures cost more than the original work. A package that's +"obvious" to the author is a half day of confusion for the recipient. +Handoff is **part of the deliverable**, not afterthought packaging. + +### Two kinds + +- **Internal** — passing work to a teammate or future-you. Branch, PR, + half-finished prototype. +- **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. + +### Task package layout + +``` +/ +├── README.md ← what this is, who it's for, how to use +├── CHANGELOG.md ← what changed since last version +├── VERIFICATION.md ← counts, checksums, sanity checks +├── manifest.json ← machine-readable metadata +├── data/ ← the actual deliverable +└── scripts/ ← only what's needed to use the package +``` + +`manifest.json` minimum fields: + +```json +{ + "name": "praxis-sample-5", + "version": "0.5.0", + "generated_at": "2026-05-18T17:00:00Z", + "source_commit": "", + "source_repo": "", + "record_count": 1234, + "schema_version": "1.0" +} +``` + +Can't fill a field → `null` and explain in README. **Never make one up.** + +### Internal handoff + +Before handoff: + +- PR description is current. Summary describes what shipped, not what + was attempted. +- Test plan in PR template filled honestly. Untested → say so, don't + bury. +- Surprising AI-assisted decisions → `## Notes for reviewer`. "AI tried + X first, didn't work because Y, working approach is Z" — saves the + reviewer a re-derivation. +- Local-only state (env vars, scratch data) documented or scripted. + "Works on my machine" is not a handoff. + +The recipient should be able to: `git checkout` the branch → read PR +description → run test plan → form an opinion — **without messaging you.** + +### External handoff (additional bar) + +- **Reproducibility.** Someone with source access can rebuild from the + commit hash in `manifest.json`. Test once before first release. +- **Verification report.** Machine-checkable (JSON or similar) showing + pre-ship checks passed. +- **Provenance.** AI-generated → record model and human-in-loop steps. + For debugging six months later, not ceremony. +- **License & attribution.** Even for internal partners. + +### What not to ship + +- Files >500 MB without a delivery-channel conversation. +- Real PII unless that's explicitly the deal. +- `.env`, secrets, API keys, internal hostnames. +- "Final final v3" filenames. Use the version field. If it's `final`, + it's `v1.0`. +- A package without a README. Even a one-line README beats none. + +### Receiving a handoff + +1. Read the README first, fully. Resist running scripts. +2. Run the verification report. Fails → stop and message the sender + before doing anything else. +3. Note any surprise — naming, missing files, version mismatch — and + send back within a day. Drift gets worse with silence. + +--- + +## Working directory expectations (this repo) + +- Small repo (~10 files). `Read` everything before acting; no need to + spawn a sub-agent for exploration. +- Don't introduce `package.json`, `Makefile`, CI configs, or other toolchain files unless explicitly asked. This is a docs repo. diff --git a/CLAUDE.md b/CLAUDE.md index 9764b2c..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,109 +1 @@ -# CLAUDE.md — team-guide - -Context for Claude Code working in this repository. - -> Sister file: `AGENTS.md` (read by Codex). The two files cover the -> same ground — keep them in sync. Whichever tool runs reads its own -> file. See `docs/07-codex.md` for the sync rules. - -## Project - -This repo holds our team's working agreements (1–3 person team, -AI-assisted "vibe coding" development). It is **documentation, not code**. -There is no build, test, or lint step. Acceptance is "a human can read -the change and would have written the same." - -## Editing rules - -When editing files in this repo: - -- One rule per bullet. If a rule needs a paragraph of justification, - split the rule out and put the justification on a `**Why:**` line. -- Lead with the rule, then `**Why:**`, then `**How to apply:**` only - when non-obvious. Skip them when the rule speaks for itself. -- No emoji. No decorative headers. No "🚀 Getting started!" energy. -- Keep each doc under ~150 lines. Past that, split. -- Examples beat prose. A 3-line code block beats a paragraph of - description. - -## Language policy - -- **Human-facing**: Chinese. `README.md`, `docs/*.md`, and the - human-fillable templates (`templates/README.md.template`, - `templates/PR_DESCRIPTION.template.md`, - `templates/HANDOFF_CHECKLIST.template.md`) are in Chinese. -- **AI-facing**: English. `CLAUDE.md`, `AGENTS.md`, - `templates/CLAUDE.md.template`, `templates/AGENTS.md.template`. Code - blocks and command examples inside Chinese docs also stay English. -- **Commit messages, PR titles, branch names, tag annotations**: English. - AI tools and search work better on English Git metadata. - -If you're an agent and you're about to write Chinese into a file the -human would never read (or vice versa), stop — you have the wrong file. - -## What goes where - -| Topic | File | -| ---------------------------------------------- | --------------------------------- | -| Human + AI work split | `docs/01-vibe-coding.md` | -| Claude Code config (CLAUDE.md, hooks, memory) | `docs/02-claude-code.md` | -| Branches, commits, PRs, tagging | `docs/03-git-workflow.md` | -| Skill catalog, planning cadence | `docs/04-skills-and-planning.md` | -| Naming, comments, code style | `docs/05-code-style.md` | -| Task packages, handoff checklists | `docs/06-handoff.md` | -| Codex usage and AGENTS.md conventions | `docs/07-codex.md` | -| Product project spec (semver, manifest, build) | `docs/08-product-spec.md` | - -## What NOT to do - -- Don't add a doc for a rule we've used once. Wait until it's bitten - twice — then write it. -- Don't write process for processes' sake. If nobody would read or - follow it, don't write it. -- Don't quote external sources at length (license / copyright). Link - instead. -- Don't translate `CLAUDE.md` / `AGENTS.md` into Chinese. They're for - AI tools. -- Don't translate Chinese docs into English "for completeness." Pick - one language per file and stick with it. - -## Commits - -- Format: `: `. Examples: - `git-workflow: clarify branch naming`, `docs: add Codex section`. -- One topic per commit. "and" in the summary means split it. -- Always include the `Co-Authored-By` trailer when AI-assisted. - -## Versioning / releases - -Two tag styles, by project type: - -- **Spec repos** (this one, other agreement docs) — date tags: - `YYYYMMDD`, with `-N` suffix for same-day reissues (`20260520-2`). - Tag from `main`. -- **Product repos** (task_assistant, authoring-tool — anything with - versioned artifacts shipped to users) — semver: `v`. Tag from - `dev`. Internal version (`0.2.4`), display version (`V0.2.4`), and - tag (`v0.2.4`) must stay in sync. See `docs/08-product-spec.md` for - the full ruleset (manifest, release-field sync list, sensitive-info - scan, minimum delivery checklist). - -Universal rules: - -- Annotated tags only. Tag messages summarize what changed. -- Tags are immutable once pushed. If a tag is wrong, cut a new one. -- This repo is a spec repo, so tagging here means a date tag. - -## Sync with AGENTS.md - -If you change this file, update `AGENTS.md` to match (and vice versa). -The two files describe the same project to different tools — drift -breaks one of them silently. Reviewer should block PRs that touch only -one side. - -## Working directory expectations - -- The repo is small (≈20 files). You can `Read` everything before - acting; you don't need to spawn a sub-agent for exploration. -- Do not introduce `package.json`, `Makefile`, CI configs, or other - toolchain files unless explicitly asked. This is a docs repo. +@AGENTS.md diff --git a/README.md b/README.md index ae7865f..acbfbc3 100644 --- a/README.md +++ b/README.md @@ -1,87 +1,71 @@ # team-guide -我们小团队的 AI 协作(vibe coding)开发约定。 -1–3 人规模,规则不多但都是真踩过的坑。 +我们小团队的 AI 协作(vibe coding)开发约定。1–3 人规模,规则不多但都是真踩过的坑。 -## 这个仓库是什么 +完整规则在 [`AGENTS.md`](AGENTS.md)(英文,给 AI 看)——本仓库的**唯一规则来源**。 +这份 README 是给人的导览,知道去哪查、怎么参与就行。 -工作方式的唯一来源——不是项目代码,是**怎么干活**。覆盖: +## 怎么用 -- 怎么用 Claude Code(CLAUDE.md、permission、hook、memory、skill) -- 怎么用 Codex(AGENTS.md、approval 模式、与 Claude Code 的分工) -- 写代码时人和 AI 怎么分工(vibe coding 守则) -- Git 工作流(分支、commit、PR、review、tag) -- Skill 管理与项目规划节奏 -- 代码与产出风格(命名、注释、README、任务包、handoff) -- 产品类项目(task_assistant 这类有版本、有发行包的)的设计与发版规范 - -每篇都很短。一条规则要超过半页才能解释清楚的,多半还不是规则——是个待讨论项。 +1. **新成员** —— 读这份 README 五分钟,再扫一眼 [AGENTS.md](AGENTS.md) 的目录。具体规则用到再翻。 +2. **新项目** —— 从 [`templates/`](templates/) 复制对应模板。新仓库根目录放 `AGENTS.md`,再放一行 `@AGENTS.md` 的 `CLAUDE.md`,让 Claude Code 和 Codex 读同一份。 +3. **不同意某条规则** —— 在本仓库开 PR 改它,不要私下绕开。 ## 语言策略 -- **给人看的**:中文。`README.md`、`docs/*.md`、人填的 template - (README、PR、handoff)都是中文。 -- **给 AI 看的**:英文。`CLAUDE.md`、`AGENTS.md`、对应 template、 - 以及中文文档里的代码块 / 命令示例。 -- **Commit / PR / 分支 / tag**:英文。AI 工具和搜索都更吃英文 metadata。 +- **给人看的(中文)**:本 README、`templates/` 里给人填的(README、PR、handoff)。 +- **给 AI 看的(英文)**:[`AGENTS.md`](AGENTS.md)、[`CLAUDE.md`](CLAUDE.md)、AI 专用模板。 +- **Git 元数据(英文)**:commit、PR 标题、分支名、tag 注释。 + +理由:AI 工具和搜索更吃英文 metadata;规则只需要一份不需要两份;中文给人在入口处看到。 ## 目录 ``` team-guide/ -├── README.md ← 你正在看(中文,给人) -├── CLAUDE.md ← Claude Code 读的项目上下文(英文) -├── AGENTS.md ← Codex 读的项目上下文(英文) -├── docs/ -│ ├── 01-vibe-coding.md ← 人 + AI 怎么分工 -│ ├── 02-claude-code.md ← CLAUDE.md / permission / hook / memory / skill -│ ├── 03-git-workflow.md ← 分支、commit、PR、review、tag -│ ├── 04-skills-and-planning.md ← skill 目录 + 规划节奏 -│ ├── 05-code-style.md ← 命名、注释、结构 -│ ├── 06-handoff.md ← 任务包、handoff 清单 -│ ├── 07-codex.md ← Codex 使用、AGENTS.md 同步规则 -│ └── 08-product-spec.md ← 产品类项目的设计与发版规范 -└── templates/ - ├── CLAUDE.md.template ← 给 AI 看(英文) - ├── AGENTS.md.template ← 给 AI 看(英文) - ├── README.md.template ← 给人填(中文) - ├── PR_DESCRIPTION.template.md ← 给人填(中文) - └── HANDOFF_CHECKLIST.template.md ← 给人填(中文) +├── README.md ← 你正在看(中文,给人) +├── AGENTS.md ← 全部规则(英文,给 AI) +├── CLAUDE.md ← 一行 @AGENTS.md import +└── templates/ ← 新项目脚手架 ``` -## 怎么用 - -1. **新成员** —— 先读 [`docs/01-vibe-coding.md`](docs/01-vibe-coding.md) 和 - [`docs/03-git-workflow.md`](docs/03-git-workflow.md),其他当参考手册查。 -2. **新项目** —— 从 `templates/` 复制对应模板到新仓库填上。新仓库 - 根目录同时放 `CLAUDE.md` 和 `AGENTS.md`,两个文件保持同步 - (见 [`docs/07-codex.md`](docs/07-codex.md))。 -3. **不同意某条规则** —— 在本仓库开 PR 改它,不要私下绕开。 +[`AGENTS.md`](AGENTS.md) 内含 7 大章: +项目背景与编辑规则 · Vibe coding · Claude Code & Codex 配置 · +Git 工作流 · 代码与产出风格 · 产品类项目(semver、manifest、发版)· +规划节奏 · Handoff。 ## 版本管理 按**项目类型**分两种 tag 风格: -- **规范类**(本仓库 team-guide、其他规约文档)—— 按日期: - `YYYYMMDD`,比如 `20260520`。同一天多次发布加 `-N` 后缀 - (`20260520-2`)。 -- **产品类**(task_assistant、authoring-tool 这种有版本、有发行包 - 的)—— semver:`v0.2.4`。三处版本号必须同步(内部 `0.2.4` / - 显示 `V0.2.4` / tag `v0.2.4`),细则见 - [`docs/08-product-spec.md`](docs/08-product-spec.md)。 +- **规范类**(本仓库 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。 通用规则: -- `main`(规范类)/ `dev`(产品类)永远是当前工作副本,随时合并。 -- Tag 一旦推到远端就不能改、不能删、不能 force-push。 -- 大改写新 tag,不动旧 tag。 -- 谁要"用某一版",告诉对方 tag 名(例:`team-guide @ 20260520`、 - `task_assistant @ v0.2.4`)就行。 +- `main`(规范类)/ `dev`(产品类)永远是当前工作副本。 +- 只用 annotated tag(`git tag -a`)。 +- Tag 一旦推到远端就不能改、不能删、不能 force-push。错了切新的。 +- 谁要"用某一版",告诉对方 tag 名(`team-guide @ 20260520`、`task_assistant @ v0.2.4`)就行。 -打 tag 的具体命令和场景见 [`docs/03-git-workflow.md`](docs/03-git-workflow.md) -的 Tag 一节。 +具体命令、什么时候切 tag、产品项目发版细则——见 [`AGENTS.md`](AGENTS.md) 的 Git workflow 和 Product projects 两节。 -最近 tag 列表:[git.simgreek.com/simgreek/team-guide/tags](https://git.simgreek.com/simgreek/team-guide/tags) +## 几条最容易踩的线(速查) + +完整版在 AGENTS.md,这里挑人最常忘的: + +- 长 session 的上下文会污染输出,新任务开新 session +- 不读 diff 就 "looks good" 是 bug 上线的标准姿势 +- 一个 session 不要同时让 Claude Code 和 Codex 改同一个文件 +- AI 试同一个方案两次报同样的错——叫停,自己上 +- 改了 `CLAUDE.md` / `AGENTS.md` 一边,另一边要在同一个 PR 里同步(本仓库已经用 `@AGENTS.md` 解决了,新项目要注意) +- 提交前 `git diff --cached` 扫一眼,密钥误提交的应急流程在 AGENTS.md 的 Sensitive-info scan 节 +- 产品发版"必改字段清单"漏一处下版就漂移——清单写进项目自己的 AGENTS.md + +## 远端 + +[git.simgreek.com/simgreek/team-guide](https://git.simgreek.com/simgreek/team-guide) · +[tags 列表](https://git.simgreek.com/simgreek/team-guide/tags) ## License diff --git a/docs/01-vibe-coding.md b/docs/01-vibe-coding.md deleted file mode 100644 index 9b3f000..0000000 --- a/docs/01-vibe-coding.md +++ /dev/null @@ -1,77 +0,0 @@ -# 01 — Vibe coding(人机协作) - -人和 AI 在团队里怎么分工。 - -## 前提 - -Claude / Codex 写大部分代码。人负责把方向:定义问题、做决策、判断 -什么算"够好可以发"。我们不是在跟 AI 比谁打字快——是用 AI 把打字时间 -省下来,多花点时间在思考上。 - -## 分工 - -**AI 干的:** - -- 读代码、解释代码 -- 拿到清晰 spec 后写第一版实现 -- 机械重构(重命名、抽函数、改类型) -- 跑测试 / build / lint,按报错迭代 -- 生成模板代码(配置、fixture、CRUD) -- 跨工作区搜索、汇总 - -**人干的:** - -- 决定要做什么、为什么做 -- 在 AI 动手前把 spec 写清楚 -- 批准任何有外溢影响的改动(依赖、schema、infra、auth、密钥) -- 合并前读完每一行 diff -- AI 已经试错两次还在打转时,叫停 -- 写 commit message 和 PR description(AI 起草,你定稿) - -如果你觉得任务正在朝"AI 替我决策"漂移,先停下来自己写一段 spec。 - -## 提示词习惯 - -- **给框架,不给步骤。** 告诉 AI 目标、约束、你已经否决了哪些方案。 - 除非步骤本身就是关键,否则别一步步指挥。 -- **点名文件。** "修一下 `eval-agent/runner.py` 里的 bug"比"修一下那个 - bug"省一次搜索。 -- **说清楚什么算完成。** "测试通过、新 flag 默认关"——可衡量。 - "干净一点"——不行。 -- **一轮一件事。** 三个不相关的请求就开三条对话或三个 session。 - 上下文混在一起,输出也会混。 -- **看到不对就 push back。** diff 写错了就直说哪里错。别接受你自己 - 不会写出来的代码。 - -## 什么时候叫停 AI、自己上 - -出现以下情况停手: - -- 同一个方案试了两次,错误信息都没变。 -- AI 在加任务里没要求的"防御性代码"。 -- diff 已经长到你一次坐下来读不完。 -- 你没法在不重新看 diff 的情况下跟同事讲清楚改了什么。 -- 它马上要做不可逆的事(删数据、force push、动 auth)——必须明确 - 确认。 - -如果你叫停了自己上,把"为什么叫停"写进 PR description——下一个人 -不至于重蹈覆辙。 - -## 验收 AI 产出 - -把 AI 的每一份 diff 当一个跑得快的实习生 PR 来 review: - -1. 能 build 吗? -2. 测试过吗——新写的测试是不是真的覆盖了新代码? -3. 改没改 spec 范围之外的文件?每个都看一遍。 -4. 加依赖了吗?看 lockfile diff。 -5. AI 加的注释一条条读。一半是噪音,删掉。 -6. 用户可见的功能要端到端跑一遍。类型检查通过 ≠ 功能正常。 - -## 反模式 - -- **上下文滚雪球。** 长 session 会带进过期假设。新任务开新 session。 -- **闭眼批准。** 不读 diff 就说"看着没问题"是 bug 上线的标准姿势。 - 读 diff。 -- **把 spec 也外包了。** "你看着办"不是提示词,是逃避。 -- **顺手改无关代码。** AI 想"既然来了顺便重构一下"——拒绝。开新任务。 diff --git a/docs/02-claude-code.md b/docs/02-claude-code.md deleted file mode 100644 index 1e50c89..0000000 --- a/docs/02-claude-code.md +++ /dev/null @@ -1,122 +0,0 @@ -# 02 — Claude Code - -我们在每个项目里怎么配置和使用 Claude Code。 - -## 配置文件 - -每个项目应该有: - -``` -/ -├── CLAUDE.md ← 项目上下文(提交进仓库) -├── AGENTS.md ← Codex / 通用 agent 上下文(提交) -└── .claude/ - ├── settings.json ← 共享设置(提交) - ├── settings.local.json ← 个人覆盖(gitignore) - └── skills/ ← 项目级 skill(提交) -``` - -`settings.local.json` **永远** gitignore。个人 API key、本地路径、 -个人 hook 调整都放这里。 - -`AGENTS.md` 见 [docs/07-codex.md](07-codex.md)——给 Claude 看 `CLAUDE.md`, -给 Codex 看 `AGENTS.md`,两个文件内容大体一致,工具读各自的。 - -## CLAUDE.md 的内容 - -每个 `CLAUDE.md` 按这个顺序回答: - -1. **这是个什么项目?** 最多两句话。 -2. **怎么跑?** Build、test、lint 命令,写成 bash 块。 -3. **架构一段话。** 入口在哪、数据怎么流。除非能省字,否则不画图。 -4. **本仓库特有的约定。** 命名、目录、那些不看注释看不出来的模式。 -5. **不要做的事。** Claude 以前在这里翻过的车,每条一行。 - -新人(人或 AI)读一遍就该能上手干活。`CLAUDE.md` 超过 100 行,说明 -它已经偷偷变成"文档"了,应该拆出去。 - -用 `templates/CLAUDE.md.template` 起手。 - -## 权限(permission) - -默认姿态:**只读自由放行,能改的都问一下。** - -`.claude/settings.json` 里可以无提示放行: - -- 所有 `Read`、`Glob`、`Grep` -- `Bash(git status)`、`Bash(git diff)`、`Bash(git log)`、`Bash(git branch)` -- 项目特定的只读命令(`Bash(npm test)`、`Bash(pytest)` 这类) - -永远要弹窗确认: - -- 工作树之外的 `Edit` / `Write` -- 带破坏动词的 `Bash`(`rm`、`mv`、`git push`、`git reset --hard`、装包) -- 任何会跟外部服务对话的 MCP 工具 - -如果你发现自己在反复批准同一类提示,跑一下 `fewer-permission-prompts` -skill——它会扫 transcript 给你列一份允许列表。 - -## Hook(钩子) - -Hook 是让 harness 自动执行规则的方式——AI 自己**不可靠地**记住"以后 -都要 X",跨 session 会忘。 - -适合用 hook 的事: - -- 文件保存后自动格式化(Prettier、ruff、gofmt) -- 阻止改受保护路径(`.env`、生成文件、`dist/`) -- 写测试路径后自动跑测试 -- session 结束 / 长任务完成时通知 - -不适合用 hook 的: - -- 一次性检查("这周记得 X 一下") -- 任何依赖 AI 判断的("觉得有必要就跑") - -通过 `update-config` skill 配置,或者直接编辑 `.claude/settings.json`。 -JSON 里每个 hook 加一行注释说明。 - -## Memory(记忆) - -Harness 有按机器的记忆系统。用法: - -- **User**:你是谁、角色、偏好。 -- **Feedback**:你给 AI 的纠正,要跨 session 保留的(带上**为什么**)。 -- **Project**:进行中工作的事实,代码里没写的(截止日期、相关方决策、 - 为什么要重构)。 -- **Reference**:外部资源指针(Linear 项目、Grafana dashboard、内网 wiki)。 - -不要把 memory 内容塞进 `CLAUDE.md`。CLAUDE.md 是项目上下文,团队共享。 -Memory 是个人的、按机器的,不进仓库。 - -不要把 memory 当便签本用。任务级别的东西塞进 plan 或 PR description。 - -## Skill(技能) - -Skill 在三个地方: - -- **用户级**(`~/.claude/skills/`)—— 装一次到处可用 -- **项目级**(`/.claude/skills/`)—— 提交进仓库,团队共享 -- **插件**—— 通过 marketplace 安装 - -同一个流程做了三次都一样,就提升成 skill。目录见 -[docs/04-skills-and-planning.md](04-skills-and-planning.md)。 - -## Sub-agent(子 agent) - -什么时候开 sub-agent(用 `Agent` 工具): - -- 任务要跨很多文件搜索,又不想把搜索结果塞进主上下文。 -- 想让另一个独立视角再看一遍设计或 diff。 -- 工作真的并行(比如同时调研三个方案)。 - -主 agent 两次工具调用就能搞定的事,别开 sub-agent。交接成本不是免费 -的。 - -## Session - -- 一个 session 一个任务。新任务开新 session。 -- session 跑长了、上下文条快满了:先收尾当前步骤,把状态总结进 plan - 或 PR draft,然后开新 session。 -- 别用 `--continue` 把昨天的 session 拉回来做新主题。陈旧上下文会 - 渗进来。 diff --git a/docs/03-git-workflow.md b/docs/03-git-workflow.md deleted file mode 100644 index 0524487..0000000 --- a/docs/03-git-workflow.md +++ /dev/null @@ -1,153 +0,0 @@ -# 03 — Git 工作流 - -小团队,流程从轻。分支、commit、PR、review、tag。 - -## 分支 - -- `main` 永远可发。不直接 push,没有例外。 -- 功能分支:`/` —— 比如 `bai/auth-retry`、 - `bai/eval-agent-rerun`。小写、连字符、你的 handle 做前缀。 -- 长期集成分支:`integration/` —— 团队同意才用。 -- 合并完删分支。老分支会污染搜索结果。 - -## Commit - -格式: - -``` -: <祈使句小结,60 字符以内> - -<可选 body —— 写改了什么、为什么,不写怎么改> -``` - -- `` 是目录或组件,小写:`eval-agent`、`task_assistant`、 - `docs`、`git-workflow`。 -- 祈使句:`add`、`fix`、`rename`,不要 `added` / `adding`。 -- Body 在 ~72 字符换行。普通改动跳过 body。 -- 一个 commit 一个主题。摘要里出现"and"——拆。 -- AI 协作的 commit 保留 Claude Code 默认加的 `Co-Authored-By` trailer。 - 别去掉。 -- Commit message 用英文(vibe coding 守则之一:给 AI 看的内容用英文)。 - -例: - -``` -eval-agent: rerun failed tasks with stable seed -docs: clarify branch naming in git-workflow -task_assistant: drop unused legacy export path -``` - -## Pull Request - -- 一个 PR 一个主题。一句话说不清楚——拆成多个 PR。 -- 标题 70 字符以内,跟 commit 摘要同一形态。 -- Description 用 `templates/PR_DESCRIPTION.template.md`。 -- 第一次 push feature 分支用 `-u`,让它跟踪远端。 -- 有可跑的东西就开 PR,draft 也行。边写边 review 比写完再 review 好。 - -## Review - -每个 PR 都要 review,包括 AI 协作出的,自己也不能跳。 - -Reviewer 检查清单: - -1. Description 跟 diff 对得上吗?diff 有惊喜——发问。 -2. 改的每个文件都看一遍。文件跟主题无关——发问为什么进了 PR。 -3. 改动不是显而易见就本地跑一遍。 -4. 新依赖、schema 变更、env var、动 auth 的代码——讲清楚理由前 - block。 -5. 评论先发**最不重要**的;merge-blocker 留到最后,让它明显是闸门。 - -作者收尾: - -- 每条评论都回应,哪怕只是"同意,已在 修"。 -- 不同意写出来 push back,不要默默忽略。 -- 合并前把噪音 commit 压一下(squash fixup commits)。 - -## 合并 - -- Feature 分支用 squash。Merge commit 留给集成分支。 -- 最终 squash message 按 commit 格式写。PR 标题通常就是好起点。 -- 合并完删分支。 - -## Tag(版本管理) - -按项目类型分两种 tag 风格: - -| 项目类型 | Tag 格式 | 例子 | 用在哪儿 | -| -------- | ------------------- | -------------------------- | ------------------------------------- | -| 规范类 | `YYYYMMDD[-N]` | `20260520`、`20260520-2` | team-guide、规约文档、内部约定仓库 | -| 产品类 | `vX.Y.Z` | `v0.2.4` | task_assistant、有版本和发行包的产品 | - -判断标准:会有"用户"拿到这个项目的版本化产物——产品类。否则——规范 -类。详细规则见 [`docs/08-product-spec.md`](08-product-spec.md)。 - -每个 tag 是 `main` 某一时刻的快照——值得指着说"我们就按这版来"。 - -通用规则(两类都适用): - -- 只在 `main`(规范类)或 `dev`(产品类)上打 tag。功能分支打 tag - 是 smell。 -- 用 annotated tag,不用 lightweight。`git tag -a` 加一两句说自上次 - tag 以来改了什么。 -- Tag 一旦推到远端就不能改、不能删、不能 force-tag。错了就再切一个。 -- Tag commit、push tag、告诉大家 tag 名字——这就是发布。 - -规范类专属:一天最多一个 tag。同一天再切一个,加 `-N` 后缀: -`20260520-2`、`20260520-3`。 - -产品类专属:semver 三元组、产品 README 必备版本字段同步、tag -message 用 ` V`——细则见 -[`docs/08-product-spec.md`](08-product-spec.md)。 - -切 tag(规范类): - -```bash -git checkout main -git pull --ff-only -git tag -a 20260520 -m "team-guide 20260520: bilingual README, dated tags" -git push origin 20260520 -``` - -切 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 -``` - -查看 / 对比: - -```bash -git tag --sort=-creatordate # 按时间倒序 -git show 20260520 # 看一个 tag 里有什么 -git log --oneline 20260513..20260520 # 两个 tag 之间改了什么 -``` - -什么时候切 tag(规范类): - -- 本仓库的 docs 改了,队友需要重新读。 -- 加了、删了或重组了 template。 -- 新的约定正式生效(不是还在讨论)。 - -什么时候**不**切 tag(规范类): - -- 改错别字、调格式、修死链 → 直接 push 到 `main`。 -- 还在讨论的草稿 → 走 PR,不打 tag。 - -产品类切 tag 跟着发版走,触发条件由[最低交付标准](08-product-spec.md#最低交付标准每次可给别人用的版本) -决定。 - -## 不要做的事 - -- 不要 `git push --force` 到 `main`。永远不要。push 到自己分支 - 也只在确定没人 pull 过的情况下。 -- 不要 `--no-verify` 跳 hook。修 hook 报的问题。 -- 不要 amend 已经 push 的 commit。已经在远端的就加新 commit。 -- 不要删或移已经 push 的 tag。错了就切新的。 -- 不要提交 `.env`、密钥、或者 ~5 MB 以上的文件——大文件先聊 - Git LFS。 -- 有不认识的 untracked 文件时,不要 `git add .` / `git add -A`。 - 按文件名加。 diff --git a/docs/04-skills-and-planning.md b/docs/04-skills-and-planning.md deleted file mode 100644 index 7d755d4..0000000 --- a/docs/04-skills-and-planning.md +++ /dev/null @@ -1,101 +0,0 @@ -# 04 — Skill 与规划 - -我们怎么管 skill 目录、小团队怎么排活。 - -## Skill 目录 - -"Skill"是 Claude Code 能调用的、命名好的可复用流程。我们维护三份: - -- **个人**(`~/.claude/skills/`)—— 私人,每人自己管。 -- **团队**(`/.claude/skills/`)—— 提交进仓库,跟项目共享。 -- **打包 / 插件** —— 从 marketplace 装。 - -### 什么时候做 skill - -工作流提升成 skill 要**同时**满足三条: - -1. 你已经用同样的方式做过三次。 -2. 步骤稳定到能写下来。 -3. 别人按你写的也会做出同样的东西。 - -只满足两条——留在你的提示词笔记里。 - -### Skill 设计规则 - -- 一个 skill 一件事。要分支判断"用户想干什么"——拆成两个。 -- 用动词短语命名:`review-pr`、`cut-release`、`rebuild-fixtures`。 - 不要 `pr-helper`。 -- Description(模型看的那行字)说**什么时候触发**,不是 skill 干啥。 - 触发由模型判断。 -- `SKILL.md` 200 行以内。长 skill 拆成阶段。 -- 例子比说明强。给一个跑通的 run。 - -### Skill review - -新 skill 当 PR 看:读、在真实任务上跑一次、merge。一个月没人用的 -skill 归档(移到 `.claude/skills/_archive/`)。 - -### 当前活跃 skill(团队) - -边走边维护。每条一行说明 + 路径。 - -``` -# 推荐安装的(marketplace 或拷贝): -# anthropic-skills:consolidate-memory — 周期性 memory 整理 -# simplify — review 改动找复用 / 质量问题 -# fewer-permission-prompts — 从 transcript 提议 allowlist -# review — review pull request -# security-review — 对 pending 改动做安全 pass - -# 团队 skill(本仓库): -# (还没有 —— 提升成 skill 后加进来) -``` - -## 规划节奏 - -我们 1–3 人。流程能保持对齐就够轻。当下做法: - -### 每周 - -- 一次异步书面同步(周一上午)。每人发: - 1. 上周交付了什么(每条一行)。 - 2. 这周准备捡什么(每条一行)。 - 3. 哪儿卡住或不清楚(**唯一**值得仔细读的部分)。 -- 周中 30 分钟实时会。议题来自上面那条"卡住或不清楚"。 - -### 每个任务 - -要超过半天的活,开工前: - -1. 写 5 行 spec:*目标 / 为什么 / 完成标准 / 范围外 / 风险*。 -2. 在 PR description 里贴上(draft PR 也行),**写代码前**。 -3. AI 要替你打字的话,这段 spec 就是提示词——直接喂进去。 - -收尾: - -1. PR description 更新到跟实际交付一致。 -2. 学到的、未来你想看到的,进 Claude memory(feedback / project 类型) - —— 见 [docs/02-claude-code.md](02-claude-code.md)。 - -### 每季度 - -留半天: - -- 重读本仓库。过期的开 PR 改。 -- 重审 skill 目录。不用的归档。 -- 跑 `consolidate-memory` 整理个人 memory 文件。 - -## 项目结构 - -工作区下开新项目: - -1. 复制 `templates/README.md.template` 和 `templates/CLAUDE.md.template`。 -2. 立刻 `git init`,哪怕项目是一次性的。一次性项目活得比你想的久。 -3. 第一个 commit 只放脚手架,没有真实代码。让 `git log` 后续好读。 -4. 把项目加进工作区 README(有了之后),让别人能发现。 - -## 规划**不是** - -- 不是 Jira ticket。两个人不需要看板。 -- 不是 Gantt 图。需要 Gantt 说明在做错的东西。 -- 不是状态秀。周一帖是为了发现卡点,不是证明你干了活。 diff --git a/docs/05-code-style.md b/docs/05-code-style.md deleted file mode 100644 index 84325ef..0000000 --- a/docs/05-code-style.md +++ /dev/null @@ -1,96 +0,0 @@ -# 05 — 代码与产出风格 - -命名、注释、结构。不论是人写的还是 AI 写的代码,都按这套来。 - -## 命名 - -- **文件** —— 小写。文档用连字符(`git-workflow.md`),Python 用 - 下划线(`task_runner.py`),JS/TS 跟生态走 kebab。匹配周围项目。 -- **函数** —— 动词短语。`loadConfig` 不是 `config`;`runTask` - 不是 `taskRunner`。 -- **变量** —— 写它**是什么**,不写它的类型。`users` 不是 - `userArray`;`retryCount` 不是 `n`。 -- **布尔** —— `is*`、`has*`、`should*`。`isReady` 不是 `ready`。 -- **常量** —— `UPPER_SNAKE_CASE` 仅用于真正的模块级常量。函数内用 - 普通 `const`。 -- **不要缩写**——除非是领域术语。`database` 不是 `db`,`request` - 不是 `req`。(Express handler 里的 `req`/`res` 是领域约定,可以。) - -## 注释 - -默认不写。要写注释,**全部**条件成立: - -- "为什么"从代码里看不出来。 -- 未来读代码的人不写注释会读错。 -- 代码本身改不清晰(重命名、抽函数、重组都试过)。 - -不要写: - -- `// increment counter` 紧挨着 `counter++` -- `// added for the auth refactor` —— 这话该在 commit message 里 -- 一大段 docstring 只是把签名复述一遍 -- 没有 owner 没有日期的 TODO —— 它们会烂掉。要么现在修,要么开 - issue,要么删了。 - -可以写: - -- 一行解释一个非显而易见的 workaround,带上**为什么**。 -- `# NOTE:` 标注会让读者意外的行为。 -- 文件头注释,仅限于这个文件做的事目录结构没说清楚。 - -## 文件结构 - -- 一个文件一个概念。一句话说不清这个文件干啥——拆。 -- 测试文件挨着代码放,除非项目本来就是平行测试树。 -- 生成文件进 `dist/` / `build/` 这类目录,进 `.gitignore`。永远 - 不改生成文件。 -- Lockfile 必须 commit,永远。 - -## 错误 - -- 在边界处(用户输入、外部 API、文件 I/O)大声失败。 -- 不要 `try/except` 吞错。捕了就处理。 -- 内部函数信任调用方,不要在三层深度上重复校验同一个输入。 -- 日志里的错要带够上下文,光看日志能调试——做的什么操作、输入是 - 什么、走的哪条路径。 - -## 测试 - -- 测行为,不测实现。一个保留行为的重构把测试搞挂了——是测试错。 -- 一个测试一个断言为佳。"啥都测的测试,挂了你不知道是哪一个挂了。" -- Fixture 和用它的测试放一起。 -- 慢 / flaky 的测试加标记或隔离,不要默默重试。 -- 没测试的新代码就是没写完——除非项目真的没有测试基础设施 - (罕见,而且这本身是个 bug)。 - -## README - -每个仓库都要有 `README.md`。按这个顺序回答: - -1. **这是什么?** 一段话。 -2. **怎么跑?** Setup / run / test 的 bash 块。 -3. **怎么开发?** 代码在哪,约定是什么。 -4. **数据从哪来 / 去哪?** 仅当不显然才写。 -5. **指针。** 关联仓库、dashboard、文档。 - -用 `templates/README.md.template`。如果你的 README 比模板短,没问题 -——把没用的 section 删掉。 - -## 交付物(任务包、数据集、导出) - -给伙伴或下游交付时: - -1. 文件名带版本:`-v.` 或 `-.`。 - 一个项目一种约定,定了别变。 -2. 配 `README` 写明 schema、生成日期、已知限制。 -3. 配验证报告(计数、checksum、合理性检查),跟交付物一起打包。 -4. 生成它的 commit hash 写进 README。 - -完整 checklist 见 [docs/06-handoff.md](06-handoff.md)。 - -## 不要做的事 - -- 不要引入第三种做某件事的方式——已经有两种了。挑一种统一。 -- 不要"为了灵活性"加配置开关,没有真实用例就别加。YAGNI。 -- 不要在功能 PR 里顺手重构无关代码。开新 PR。 -- 不要没量就先优化。"可能慢"不是测量结果。 diff --git a/docs/06-handoff.md b/docs/06-handoff.md deleted file mode 100644 index 73a442b..0000000 --- a/docs/06-handoff.md +++ /dev/null @@ -1,103 +0,0 @@ -# 06 — Handoff(交接) - -任务包、交付物、团队成员之间或对外部消费方的交接。 - -## 为什么这事重要 - -交接出问题的成本比原工作高。作者觉得"显然就是这么用的"的包,到接收方 -手里是半天的迷茫。把交接当**交付物的一部分**对待,不是事后包装。 - -## 两种 handoff - -1. **内部** —— 把工作交给队友(或未来的你)。通常是分支、PR、半成品 - 原型。 -2. **外部** —— 给伙伴、客户或下游 pipeline 发版本化产物。通常是 zip、 - 数据集、release。 - -两种都用 `templates/HANDOFF_CHECKLIST.template.md`。外部的标准更高。 - -## 任务包 - -我们发的任务包(比如 `praxis-sample-5.zip`、 -`task-assistant-v0.2-handoff-*.zip`)必须包含: - -``` -/ -├── README.md ← 这是什么、给谁用、怎么用 -├── CHANGELOG.md ← 自上一版改了什么 -├── VERIFICATION.md ← 计数、checksum、合理性检查 -├── manifest.json ← 机器可读的元数据 -├── data/ ← 真正的交付物 -└── scripts/ ← 用这个包必须的脚本 -``` - -`manifest.json` 至少要有: - -```json -{ - "name": "praxis-sample-5", - "version": "0.5.0", - "generated_at": "2026-05-18T17:00:00Z", - "source_commit": "", - "source_repo": "", - "record_count": 1234, - "schema_version": "1.0" -} -``` - -填不出的字段写 `null`,在 README 里解释。**永远不要瞎编**。 - -## 内部 handoff(分支 / PR) - -交出去之前: - -- PR description 是最新的。Summary 写实际交付了什么,不是尝试过什么。 -- PR template 里的 "test plan" 老老实实填。没测就说没测——别埋。 -- AI 协作中让你意外的决策放进 `## Notes for reviewer`。"AI 先试了 X - 不行因为 Y,最后用了 Z"——省 reviewer 重推一遍。 -- 本地状态(env var、临时数据)要文档化或脚本化。"在我机器上能跑" - 不算交接。 - -接收方应该能: - -1. `git checkout` 这个分支 -2. 读 PR description -3. 跑 test plan -4. 形成自己的判断 - -—— **不用问你**。如果接收方还要私聊你,handoff 就是不完整的。 - -## 外部 handoff(版本化产物) - -标准更高。除上面任务包内容外: - -- **可重现。** 有源码访问的人能从 `manifest.json` 里的 commit hash - 重建产物。第一次发布前测一遍。 -- **验证报告。** 一份机器可读(JSON 之类)的报告,记录预发检查的 - 通过情况。写清楚检查了什么、结果是什么。 -- **来源(provenance)。** AI 协助生成的,写明用的哪个模型、人工 - 审核步骤是什么。不是为了仪式感——是为了半年后产物有问题时好查。 -- **License 与署名。** 内部伙伴也要写。明确他们能用、不能用。 - -## 不要发的东西 - -- 没聊过传输渠道的 ~500 MB 以上文件。 -- 含真实 PII 的内容——除非交付协议里就明确包含。 -- `.env`、密钥、API key、内部主机名。 -- "final final v3" 命名。用 version 字段。要是 final,那就是 `v1.0`。 -- 没有 README 的包。一行 README 也比没有强。 - -## 收到 handoff 时 - -你是接收方: - -1. 先**完整读** README。忍住直接跑脚本的冲动。 -2. 跑一遍验证报告。不通过——停下来联系发送方再做任何事。 -3. 任何意外(命名、缺文件、版本不对)一天内反馈给发送方。drift 不 - 反馈只会越来越歪。 - -## 模板 - -- `templates/HANDOFF_CHECKLIST.template.md` —— 每次交接填一份,跟 - 包一起发。 -- `templates/PR_DESCRIPTION.template.md` —— 内部 handoff 走 PR 用。 diff --git a/docs/07-codex.md b/docs/07-codex.md deleted file mode 100644 index 49ae299..0000000 --- a/docs/07-codex.md +++ /dev/null @@ -1,114 +0,0 @@ -# 07 — Codex - -我们怎么在团队里用 Codex(CLI 与 IDE 集成),以及 `AGENTS.md` 怎么写。 - -## 为什么要规范 - -Codex 不读 `CLAUDE.md`。Claude Code 默认不读 `AGENTS.md`。两个工具在 -同一个仓库里干活,看的是不同的"项目说明书"。如果只写一份,另一边就 -是裸奔。 - -我们的做法:**两份都写,内容保持同步**。哪边的工具进来读哪边的文件。 - -## 文件分工 - -``` -/ -├── CLAUDE.md ← Claude Code 读的项目上下文 -├── AGENTS.md ← Codex CLI / Codex IDE 读的项目上下文 -└── docs/... ← 给人读的文档(中文) -``` - -两个文件**内容大体一致**:项目是什么、怎么跑、架构、本仓库特有的 -约定、不要做什么。 - -它们的区别是: - -- `CLAUDE.md` 偶尔会引用 Claude Code 特有的概念(skill、sub-agent、 - permission mode、`.claude/settings.json`)。 -- `AGENTS.md` 偶尔会引用 Codex 特有的概念(approval 模式、 - `~/.codex/config.toml`、MCP server 配置)。 -- 双方共有的部分(项目背景、命名约定、语言策略、commit 格式)必须 - 完全一致。 - -## 同步责任 - -谁改了 `CLAUDE.md`,谁顺手改 `AGENTS.md`(反之亦然)。在 PR 描述里 -加一句"Synced AGENTS.md"或"Synced CLAUDE.md"——reviewer 一眼就能确认。 - -如果 PR 只改了一边,reviewer **block** 这个 PR,让作者补上。 - -要是哪天发现两边内容已经漂移得太远,开一个专门的 PR 重新对齐, -不要在功能 PR 里捎带修。 - -## Codex 使用约定 - -### 启动方式 - -- 终端:`codex`(不指定 prompt 进交互模式)或 `codex ""`(一次性 - 任务)。在仓库根目录启动,让它能找到 `AGENTS.md`。 -- IDE:用官方插件(VS Code / JetBrains)。仓库根目录的 `AGENTS.md` - 自动加载。 - -### Approval 模式 - -默认用 `on-request`(命令前问一下)。机器是个人的、风险可控的环境 -才用 `on-failure` 或 `never`。生产环境、共享机器、不熟悉的仓库—— -保持 `on-request`。 - -调整方式见 Codex 文档;个人偏好放进 `~/.codex/config.toml`,**不要** -提交进仓库。 - -### 沙盒(sandbox) - -- 写代码 + 跑测试:`workspace-write` + 网络 off。够用了。 -- 需要联网装包 / fetch 资源:临时切 `workspace-write` + 网络 on,跑完 - 切回。 -- `danger-full-access` 几乎不用。除非你知道自己在干嘛而且代价能承担。 - -### 不要让 Codex 干的事 - -跟 Claude Code 一样: - -- 删数据、`git push --force`、改 auth、动密钥——**人决策**。 -- 改 schema、加依赖、改 CI——**人审批**。 -- 跨仓库的改动——**手动协调**,不要让 agent 一次推两个仓库。 - -## AGENTS.md 写法 - -每个项目的 `AGENTS.md` 按这个顺序写: - -1. **项目** —— 一两句话定位。不要超过两句。 -2. **怎么跑** —— Build / test / lint 命令,bash 块。 -3. **架构** —— 一段话。入口、数据流、核心模块。能省字就省字。 -4. **本仓库特有约定** —— 命名、目录、那些代码里看不出来的模式。 -5. **语言策略** —— 哪些文件是中文(人看),哪些是英文(AI 看), - commit / PR / branch / tag 用什么语言。 -6. **不要做的事** —— 翻过的车,每条一行。 - -100 行以内是目标,超出说明它在朝"通用文档"漂移,该拆。 - -模板见 `templates/AGENTS.md.template`。 - -## 工具选择建议 - -不是非此即彼,但有偏好: - -- **写 docs / 写规范** —— Claude Code(这个仓库就是它写的)。 -- **大段重构 / 跨多文件功能** —— Claude Code,因为有 plan mode 和 - sub-agent。 -- **窄范围编辑、跑个测试、改个配置** —— Codex CLI,启动快。 -- **IDE 内 inline 改一段** —— Codex IDE 插件或 Cursor,看习惯。 - -两个工具混着用没问题,只要: - -- 一个 session 一个工具(别又开 Claude Code 又开 Codex 改同一个文件, - 互相覆盖很难追)。 -- 两边产出的 commit 都按本仓库的 commit 格式([03-git-workflow.md](03-git-workflow.md))。 - -## 配置同步与个人覆盖 - -- 项目级:`AGENTS.md`、`CLAUDE.md`、`.claude/settings.json` 都进仓库。 -- 个人级:`~/.codex/config.toml`、`~/.claude/settings.json`、 - `.claude/settings.local.json`——**永远不进仓库**,gitignore 已经覆盖。 -- 个人 token 永远不写进仓库里的任何文件,包括 `AGENTS.md`。 diff --git a/docs/08-product-spec.md b/docs/08-product-spec.md deleted file mode 100644 index 619420d..0000000 --- a/docs/08-product-spec.md +++ /dev/null @@ -1,291 +0,0 @@ -# 08 — 产品类项目规范 - -把 task_assistant 这类**有版本、有发行包、有用户使用**的项目从设计 -到发布要遵循的约定写下来。规范性文件(像本仓库 team-guide 自己)按 -日期 tag;产品代码按 semver。 - -## 两类项目的分界 - -| 维度 | 规范类(team-guide、规约文档) | 产品类(task_assistant、authoring-tool) | -| ---------- | ----------------------------- | ---------------------------------------- | -| 内容 | 文档、约定、模板 | 可执行代码、可发行的产物 | -| Tag 格式 | `YYYYMMDD` / `YYYYMMDD-N` | `v..` | -| 验收 | 人能读懂 | 测试通过、能跑起来 | -| 分发渠道 | Git 仓库本身 | Git(源码)+ 分发渠道(OpenList、HF 等) | -| 版本字段同步 | 没有 | 多处必须同步(见下文) | -| 用户 | 团队成员 | 真实使用者 | - -不确定一个项目是哪类,问自己:"会有'用户'拿到这个项目的版本化产物 -吗?" 会就是产品类。 - -## 版本号 - -**Semver 三元组**:`major.minor.patch`。 - -- **major** —— 不向后兼容的改动(schema 改了、CLI 参数改了、产物格式改了) -- **minor** —— 向后兼容的功能增加 -- **patch** —— bug fix、性能优化、内部重构 - -我们的项目内部用三种写法,**三处必须同步**: - -| 用途 | 格式 | 例子 | 在哪儿出现 | -| ------------ | ------------------ | ---------------- | ----------------------------------- | -| 内部版本号 | `X.Y.Z` | `0.2.4` | `package.json`、`pyproject.toml` | -| 显示版本号 | `VX.Y.Z` | `V0.2.4` | UI 胶囊、README 标题、release note | -| Git tag | `vX.Y.Z` | `v0.2.4` | Git tag 名 | - -发布时**一个不能漏**的同步检查清单(用 task_assistant 举例): - -``` -package.json "version": "0.2.4" -public/index.html version chip 初始值 -server.js fallback 版本 -scripts/build-release.js fallback 版本 + release notes -scripts/build-release-windows.js fallback 版本 + release notes -README.md 标题、版本状态段 -README.en.md 同上 -``` - -每个项目都该在 README 里列一份"发版必改的版本字段"清单,**位置写 -死**。漏一处下一版就漂移。 - -## Tag - -```bash -git tag -a v0.2.4 HEAD -m " V0.2.4" -git push v0.2.4 -``` - -规则: - -- 用 annotated tag(`-a`),不用 lightweight。 -- Tag message 用英文,格式 ` V`,跟 displayVersion - 一致。 -- 一个版本一个 tag。同版本不同平台不要分多个 tag。 -- 已经用于发行的 tag **不要移动**。错了发 patch(`v0.2.5`)覆盖。 -- 误打的 tag 在**没用于发行前**可以删: - -```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 -``` - -## 分支策略 - -产品类项目至少有: - -- **`dev`** —— 默认协作分支。日常开发、bug 修复、文档更新、发行前 - 准备都进这里。 -- **功能分支** —— `/`,开 PR 合到 `dev`。 - -不留含义不清的 `master`。需要稳定分支时用明确名字,比如: - -``` -release/v0.3 -release/v0.3-hotfix -``` - -发布从 `dev` 起步——拉取 → 检查 → 改版本号 → 打 tag → 构建 → 上传。 - -## Git 与分发分家 - -**Git 管源码,分发渠道(OpenList / Hugging Face / 其他)管发行物**。 -两者职责不混。 - -进 Git: - -- 源代码、构建脚本、文档、协作规范、必要的小型静态资源、模板、 - role / 配置表。 - -不进 Git: - -``` -config/ 本地配置 -logs/ 运行日志 -feedback-records/ 用户反馈 -generated_task_packages/ 任务输出 -reports/ 验证报告 -runtime-temp/ 临时运行态 -release/ release-build/ release-dev/ release-merge/ -.venv/ __pycache__/ node_modules/ -``` - -进分发渠道(典型路径,按项目调): - -``` -//dist/ 面向使用者的发行 zip + manifest -//feedback// 用户上传的反馈 -``` - -发行 zip **必须自包含**:用户解压点击就能跑,不在用户机器上装 -依赖。具体内容随项目变,但原则不变。 - -## Manifest - -每次发布在分发渠道根目录放一份 `manifest.json`,客户端启动时读它判 -断有没有更新: - -```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": "" -} -``` - -上传后**重新拉一遍** manifest,肉眼对一遍 size 和 sha256 是不是新的。 -看到 size 跟旧版一致——分发渠道有缓存或上传出错。 - -## 更新机制 - -我们做的是"用户确认式更新",不是无人值守强推: - -1. 客户端启动时拉 manifest,比版本号。 -2. 有新版**提示用户**,不直接下载。 -3. 用户点同意,下载到本地。 -4. 用户点安装,重启生效。 - -任何一步不要替用户跳过。这条往后写进每个产品的 `CLAUDE.md` / -`AGENTS.md` 的"Don'ts"。 - -## 反馈与日志 - -反馈走"本地优先 + 异步上传": - -``` -本地: - feedback-records/feedback--.json - logs/-YYYY-MM-DD.jsonl - -云端(上传成功后): - //feedback//.json -``` - -规则: - -- 上传**失败不影响本地保存**。UI 提示"本地已存,上传失败可重试"。 -- 反馈和日志**必须脱敏**:API key、Bearer token、cookie、password、 - secret、私密账号——发上去之前在客户端就抹掉。 -- 排查问题时让用户走反馈页提交,**不要**让用户直接发 `config/` 或 - 完整日志目录。 - -## 敏感信息检查 - -提交前每次都做: - -```bash -git diff --cached -``` - -定期跑关键词扫描(PowerShell 例子见 task_assistant 的 -COLLABORATION_AND_RELEASE_WORKFLOW.md,bash 大致等价): - -```bash -git grep -nE "sk-|hf_|Bearer |apiKey|ANTHROPIC_API_KEY|OPENAI_API_KEY|password|secret" \ - -- ':!*.lock' ':!vendor/**' ':!**/__pycache__/**' -``` - -命中**必须人工判断**,不能照单提交,也不能照单删(注释里的 demo -key 跟真 key 都会命中)。 - -误提交真密钥的应急流程: - -1. **立刻**让对应 key/token 失效。 -2. 删除或更换本地配置。 -3. 通知协作者。 -4. 评估要不要重写 Git 历史(`git filter-repo` 或团队约定的方式)。 - -只追加一个"删除 key"的 commit 是**不够安全**的——历史里仍然能看到。 - -## 发版流程(标准动作) - -```bash -# 1. 同步 -git checkout dev -git pull --ff-only dev -git status --short --branch - -# 2. 检查 - - - -# 3. 改版本号(按本项目的"必改清单"逐项改) -# package.json、UI 胶囊、server.js、build script、README - -# 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. 构建 - - -# 6. 上传 manifest + zip 到分发渠道,验证 size/sha256 -``` - -## 产品 README 必备段落 - -每个产品类项目的 README,在通用 README 模板基础上,**额外**包含: - -- **版本状态段** —— 当前源码版本、内部版本号、协作分支、协作仓库、 - 历史迁移来源(如果有)、默认本地服务地址(如果有)、默认输出 - 目录。 -- **快速启动段** —— 按平台分(Windows / macOS / Linux),覆盖 - 解压、启动、访问、关闭。 -- **发行包内置内容清单** —— 让用户知道完整包应该有什么。 -- **发版必改字段清单** —— 给开发者的,写明哪些文件要同步改版本号。 - -人填模板见 [`templates/README.md.template`](../templates/README.md.template); -产品项目按上面清单加段落。 - -## 最低交付标准(每次"可给别人用"的版本) - -照搬 task_assistant 的清单,按项目改: - -- [ ] `/dev` 有对应 commit -- [ ] `` 有对应 tag(`v`) -- [ ] `package.json` / `pyproject.toml` 版本正确 -- [ ] UI 上版本胶囊显示正确 -- [ ] Lint / typecheck / test 全通过 -- [ ] 分发渠道 manifest 指向正确平台包 -- [ ] manifest 的 size / sha256 与实际文件一致 -- [ ] 发行包解压点击启动脚本即可运行 -- [ ] 包内**没有** API key、日志、用户反馈、生成产物、验证报告 - -任意一项没勾——不算"可给别人用"。 - -## 项目里要落地什么 - -新建产品类项目时,除了 [`docs/02-claude-code.md`](02-claude-code.md) -里的标准(`CLAUDE.md` + `AGENTS.md` + `.claude/`),还要: - -1. **`docs/COLLABORATION_AND_RELEASE_WORKFLOW.md`**(或类似名字)—— - 这份团队规范的项目特化版,包含本项目的版本字段清单、构建命令、 - 分发路径。task_assistant 那份就是范本。 -2. **`scripts/build-release.*`** —— 构建脚本,输出 zip + 更新 - `manifest.json`。 -3. **发版必改字段清单** —— 写进 `CLAUDE.md` / `AGENTS.md` 或上面那份 - workflow 里,**唯一来源**。 -4. **CHANGELOG.md** —— 一个版本一段,按 semver 顺序排,简述用户能感 - 知的改动。 - -不必落地的(YAGNI): - -- 复杂的发版编排工具(Lerna、Changesets)—— 人手够了。 -- 自动化 release notes 生成 —— commit message 够好就够用。 -- 多环境配置体系 —— 真有需要再说。