Compare commits
2
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
17671b2b22 | ||
|
|
c8ce92a2ed |
No files matched your search
@@ -36,8 +36,9 @@ read the change and would have written the same."
|
||||
split the rule out and put the reason on a `**Why:**` line.
|
||||
- Lead with the rule, then `**Why:**`, then `**How to apply:**` only
|
||||
when the rule isn't self-evident.
|
||||
- No emoji. No decorative headers. No "🚀 Getting started!" energy.
|
||||
- Keep AGENTS.md under ~800 lines. Past that, split.
|
||||
- No emoji.
|
||||
- Keep AGENTS.md under ~600 lines. Past that, split a section into
|
||||
`library/`.
|
||||
- Examples beat prose. A 3-line code block beats a paragraph.
|
||||
|
||||
## Language policy
|
||||
@@ -74,9 +75,9 @@ When starting a new project, prefer the single-file approach: write
|
||||
|
||||
### The premise
|
||||
|
||||
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.
|
||||
AI writes most of the code. Humans steer: framing problems, making
|
||||
decisions, deciding what's good enough. The point of AI assistance is
|
||||
to skip typing, not to skip thinking.
|
||||
|
||||
### The split
|
||||
|
||||
@@ -96,59 +97,72 @@ making decisions, deciding what's good enough. We're not racing the AI
|
||||
- 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)
|
||||
- Stop AI when it's tried twice and is going in circles
|
||||
- Sign off on commit messages and PR descriptions (AI drafts; human signs)
|
||||
|
||||
If a task feels like it's drifting toward "AI decides", stop and write
|
||||
a spec yourself first.
|
||||
### Spec requirement
|
||||
|
||||
### Prompt habits
|
||||
If the task description from the human is shorter than ~3 sentences and
|
||||
the work touches more than one file, the AI must **stop and ask for a
|
||||
5-line spec** before writing code:
|
||||
|
||||
- **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.
|
||||
```
|
||||
Goal: <what should be true after this task>
|
||||
Why: <one sentence>
|
||||
Done when: <measurable acceptance>
|
||||
Out of scope: <things explicitly not to touch>
|
||||
Risks: <what could go wrong>
|
||||
```
|
||||
|
||||
### When to take over
|
||||
Don't infer the spec silently. Vague task + silent inference is the most
|
||||
common cause of AI rework.
|
||||
|
||||
Stop letting AI drive when:
|
||||
### Prompt habits (rules for human input that improve AI output)
|
||||
|
||||
- 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.
|
||||
- **Frame, don't dictate.** Goal + constraints + what's been ruled out.
|
||||
Don't prescribe steps unless the steps are the point.
|
||||
- **Name files.** "Fix the bug in `<repo>/<file>.py`" beats "fix the bug."
|
||||
- **Say what done looks like.** Measurable phrasing — "tests pass and
|
||||
the new flag defaults to off." Not "make it cleaner."
|
||||
- **One task per session.** Unrelated asks → separate sessions.
|
||||
- **Push back on bad output.** Point at the wrong part specifically.
|
||||
|
||||
When you take over, write *why* in the PR description so the next person
|
||||
doesn't repeat the loop.
|
||||
### When AI must stop and surface to the human
|
||||
|
||||
### Verifying AI output
|
||||
AI stops driving and surfaces the situation to the human when:
|
||||
|
||||
Treat every AI diff like a fast junior's PR:
|
||||
- The same approach has failed twice with the same error.
|
||||
- The task is asking AI to add code (validation, retry logic, defensive
|
||||
guards) the spec didn't request.
|
||||
- The current diff has grown past ~300 lines or touches >5 files when
|
||||
the spec called for a narrower change.
|
||||
- AI is about to do something irreversible (delete data, force-push,
|
||||
rotate auth, drop a database, modify a production config).
|
||||
|
||||
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.
|
||||
In each case, AI summarizes the situation and asks for direction. Don't
|
||||
keep iterating.
|
||||
|
||||
### Anti-patterns
|
||||
### Output verification (AI runs this on its own diffs before declaring done)
|
||||
|
||||
- **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.
|
||||
1. Does the build / typecheck pass?
|
||||
2. Do tests pass — and do new tests actually exercise the new code?
|
||||
3. Are there files in the diff outside the stated scope? If yes, justify
|
||||
each or revert.
|
||||
4. Did this PR add dependencies? If yes, name them in the summary.
|
||||
5. Are there AI-generated comments restating what the code says? Delete.
|
||||
6. For user-facing changes: state how the change was exercised end-to-end.
|
||||
Type-check passing is not evidence of working software.
|
||||
|
||||
### Anti-patterns AI must avoid
|
||||
|
||||
- **Snowballing context.** Long single session covering multiple
|
||||
unrelated tasks; stale assumptions leak across tasks.
|
||||
- **Refactor drift.** "While I'm here, let me also clean up X." Open a
|
||||
separate task instead.
|
||||
- **Comment padding.** Adding obvious or restating comments to make a
|
||||
diff look thorough.
|
||||
- **Silent scope expansion.** Touching files not implied by the task
|
||||
without flagging them in the summary.
|
||||
|
||||
---
|
||||
|
||||
@@ -158,64 +172,49 @@ Treat every AI diff like a fast junior's PR:
|
||||
|
||||
```
|
||||
<repo>/
|
||||
├── AGENTS.md ← canonical spec, committed
|
||||
├── CLAUDE.md ← committed, single line: @AGENTS.md
|
||||
├── 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.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
|
||||
### Per-project AGENTS.md content
|
||||
|
||||
In this order:
|
||||
Order: **Project** (≤2 sentences) → **Run it** (bash blocks) →
|
||||
**Architecture** (one paragraph + key files) → **Conventions specific
|
||||
to this repo** → **Don'ts** (things AI got wrong here before).
|
||||
|
||||
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."
|
||||
|
||||
Skeleton to copy into a new project's `AGENTS.md`:
|
||||
Past 100 lines → split. Skeleton:
|
||||
|
||||
```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.
|
||||
> Reference: 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 <…>
|
||||
```
|
||||
|
||||
@@ -223,143 +222,93 @@ Key files:
|
||||
|
||||
### Permissions (Claude Code)
|
||||
|
||||
Default: prompt for risky, allow read-only freely.
|
||||
Default: prompt for risky, allow read-only. **Why:** keeps friction
|
||||
low for safe ops while preserving review of mutations.
|
||||
|
||||
In `.claude/settings.json`, allow without prompting:
|
||||
Allow without prompt: all `Read`/`Glob`/`Grep`, read-only Bash
|
||||
(`git status`, `git diff`, `git log`, `git branch`, project test
|
||||
runners).
|
||||
|
||||
- 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.
|
||||
Always prompt: `Edit`/`Write` outside the working tree; destructive
|
||||
Bash (`rm`, `mv`, `git push`, `git reset --hard`, package installs);
|
||||
any MCP tool hitting a remote service.
|
||||
|
||||
### 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.
|
||||
- **Approval**: default `on-request`. **Why:** unfamiliar repos and
|
||||
shared machines need command-level review.
|
||||
- **Sandbox**: default `workspace-write` + network off. Turn network
|
||||
on only when fetching/installing, then off again.
|
||||
- Personal Codex prefs go in `~/.codex/config.toml`, never committed.
|
||||
|
||||
### Hooks
|
||||
|
||||
Hooks enforce rules automatically. AI **does not reliably remember**
|
||||
"from now on do X" across sessions; hooks do.
|
||||
AI does not reliably remember "from now on do X" across sessions —
|
||||
hooks enforce automatically.
|
||||
|
||||
Use hooks for:
|
||||
Use for: auto-format on edit, block writes to protected paths
|
||||
(`.env`, generated files, `dist/`), auto-test after writing test files,
|
||||
session-stop notifications.
|
||||
|
||||
- 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.
|
||||
Don't use for: one-off reminders, anything depending on AI judgment.
|
||||
|
||||
### Memory
|
||||
|
||||
Per-machine memory system. Use it for:
|
||||
Per-machine. Use for: who you are (User), corrections that should
|
||||
persist across sessions with the *why* (Feedback), facts about
|
||||
ongoing work that aren't in code (Project), pointers to external
|
||||
resources (Reference).
|
||||
|
||||
- **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.
|
||||
Memory is personal and per-machine — never substitute for AGENTS.md.
|
||||
Task-scoped state goes in plans or PR descriptions, not memory.
|
||||
|
||||
### Skills
|
||||
|
||||
Skills live in three places:
|
||||
Locations: user (`~/.claude/skills/`), project
|
||||
(`<repo>/.claude/skills/`), plugin marketplace.
|
||||
|
||||
- **User skills** (`~/.claude/skills/`) — installed once, available
|
||||
everywhere
|
||||
- **Project skills** (`<repo>/.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.
|
||||
Promote a workflow to a skill when **all three** hold: done the same
|
||||
way 3+ times, steps stable enough to write down, someone else would do
|
||||
it the same way given the spec.
|
||||
|
||||
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.
|
||||
- Verb-phrase names (`review-pr`, `cut-release`), not nouns
|
||||
(`pr-helper`).
|
||||
- Description tells the model **when to invoke**, not what the skill
|
||||
does.
|
||||
- `SKILL.md` under 200 lines.
|
||||
|
||||
Recommended installs:
|
||||
Recommended installs (read each skill's own description for what it
|
||||
does):
|
||||
|
||||
```
|
||||
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
|
||||
consolidate-memory simplify fewer-permission-prompts review security-review
|
||||
```
|
||||
|
||||
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.
|
||||
Spawn one when: cross-file search and you don't want results in main
|
||||
context, second independent read on a design or diff, genuinely parallel
|
||||
work (e.g. three options to research). Don't spawn for tasks doable 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.
|
||||
- Don't `--continue` yesterday's session for a new topic.
|
||||
|
||||
### Tool selection (mixing Claude Code + Codex)
|
||||
### Mixing Claude Code + Codex
|
||||
|
||||
Both fine; mild preferences:
|
||||
Both fine. **Don't** run two tools editing the same file simultaneously
|
||||
— overwrites are hard to trace.
|
||||
|
||||
- **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.
|
||||
Mild preferences: docs/specs and large refactors → Claude Code (plan
|
||||
mode, sub-agents); narrow edits and quick test runs → Codex CLI
|
||||
(faster startup); in-IDE inline → Codex IDE plugin or Cursor.
|
||||
|
||||
---
|
||||
|
||||
@@ -368,10 +317,10 @@ are hard to trace.
|
||||
### Branches
|
||||
|
||||
- `main` (spec repos) / `dev` (product repos) is always shippable. No
|
||||
direct pushes, no exceptions.
|
||||
- Feature branches: `<owner>/<short-slug>` — `bai/auth-retry`,
|
||||
`bai/eval-agent-rerun`. Lowercase, hyphens, handle prefix.
|
||||
- Long-lived integration: `integration/<topic>` — only by team agreement.
|
||||
direct pushes.
|
||||
- Feature branches: `<short-slug>`, lowercase, hyphenated. Project may
|
||||
prefix with owner (`<owner>/<slug>`) — follow the project's existing
|
||||
convention.
|
||||
- Delete branches after merge.
|
||||
|
||||
### Commits
|
||||
@@ -382,10 +331,8 @@ are hard to trace.
|
||||
<optional body — what changed and why, not how>
|
||||
```
|
||||
|
||||
- `<area>` is a directory or component, lowercase: `eval-agent`,
|
||||
`task_assistant`, `docs`, `git-workflow`.
|
||||
- `<area>` is a directory or component, lowercase.
|
||||
- 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.
|
||||
@@ -404,42 +351,35 @@ task_assistant: drop unused legacy export path
|
||||
- Title under 70 chars, same shape as commit summary.
|
||||
- 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.
|
||||
(checkbox list, honest about what was and wasn't tested) /
|
||||
**Out of scope** (optional) / **Notes for reviewer** (optional, for
|
||||
surprising AI decisions). Add an `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.
|
||||
|
||||
### Review
|
||||
### Review (when AI is reviewer)
|
||||
|
||||
Every PR reviewed before merge — own AI-assisted PRs included.
|
||||
When AI reviews a PR, run these checks in order:
|
||||
|
||||
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 <commit>".
|
||||
- Disagree → push back in writing. Don't silently ignore.
|
||||
- Squash fixup commits before merge if history is noisy.
|
||||
1. Does the PR description match the actual diff? Flag surprises.
|
||||
2. Read every changed file. Files outside the stated topic → flag with
|
||||
"this file is not implied by the description".
|
||||
3. Run the change locally if correctness isn't obvious from reading.
|
||||
4. Block until justified: new deps, schema changes, env var additions,
|
||||
auth-touching code, anything affecting persisted data.
|
||||
5. Output critical findings (merge-blockers) last in the review summary
|
||||
so they're visually distinct from minor comments.
|
||||
|
||||
### Merging
|
||||
|
||||
- Squash for feature branches. Merge commits reserved for integration.
|
||||
- Squash for feature branches.
|
||||
- Final squash message follows commit format.
|
||||
- Delete the branch on merge.
|
||||
|
||||
### Tagging
|
||||
### Tagging (this repo)
|
||||
|
||||
Tags are dated: `YYYYMMDD`, with `-N` suffix for same-day reissues
|
||||
(`20260520-2`). Tag from `main`.
|
||||
Tags are dated: `<YYYYMMDD>`, with `-N` suffix for same-day reissues
|
||||
(e.g. `<YYYYMMDD>-2`). Tag from `main`.
|
||||
|
||||
Rules:
|
||||
|
||||
@@ -447,29 +387,28 @@ Rules:
|
||||
- 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.
|
||||
- Max one tag per day; use `-N` for same-day reissues.
|
||||
|
||||
Cut a tag:
|
||||
|
||||
```bash
|
||||
git checkout main && git pull --ff-only
|
||||
git tag -a 20260520 -m "team-guide 20260520: bilingual policy"
|
||||
git push origin 20260520
|
||||
git tag -a <YYYYMMDD> -m "team-guide <YYYYMMDD>: <summary>"
|
||||
git push origin <YYYYMMDD>
|
||||
```
|
||||
|
||||
Inspect:
|
||||
|
||||
```bash
|
||||
git tag --sort=-creatordate
|
||||
git show 20260520
|
||||
git log --oneline 20260513..20260520
|
||||
git show <YYYYMMDD>
|
||||
git log --oneline <prev-tag>..<this-tag>
|
||||
```
|
||||
|
||||
When to cut a tag:
|
||||
|
||||
- Docs changed in a way teammates need to re-read.
|
||||
- A new convention is now in effect (not just proposed).
|
||||
- A library/ entry was added, removed, or restructured.
|
||||
- Rules changed in a way that affects how AI should behave on tasks.
|
||||
- A `library/` entry was added, removed, or restructured.
|
||||
|
||||
When **not** to cut a tag:
|
||||
|
||||
@@ -482,15 +421,14 @@ semver `vX.Y.Z`). Each project documents its own scheme in its own
|
||||
|
||||
### Don'ts
|
||||
|
||||
- No `git push --force` to `main`. Period. To your own branch only if
|
||||
certain nobody pulled it.
|
||||
- No `git push --force` to `main` / `dev` — ever.
|
||||
- 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.
|
||||
- No committing `.env`, secrets, or files >5 MB without explicit
|
||||
approval (Git LFS or out-of-band).
|
||||
- No `git add .` / `git add -A` when untracked files are present that
|
||||
weren't explicitly part of the task. Stage by name.
|
||||
|
||||
---
|
||||
|
||||
@@ -592,52 +530,39 @@ Current entries:
|
||||
|
||||
- [`library/git-upload/`](library/git-upload/SPEC.md) — what to commit,
|
||||
what not to, how to recover from leaked secrets.
|
||||
- [`library/nodejs-project/`](library/nodejs-project/SPEC.md) — task
|
||||
execution SOP for Node.js / Next.js projects (entry → frame → sync →
|
||||
edit → encoding → verify → commit → push → release).
|
||||
|
||||
Promotion criteria, layout, and adding rules: see
|
||||
[`library/README.md`](library/README.md).
|
||||
|
||||
---
|
||||
|
||||
## 6. Planning cadence
|
||||
## 6. Per-task spec
|
||||
|
||||
1–3 person team. Lightest process that keeps us aligned.
|
||||
Before AI writes code on a task that touches more than one file:
|
||||
|
||||
### Weekly
|
||||
1. Confirm or produce a 5-line spec.
|
||||
|
||||
- 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.
|
||||
```
|
||||
Goal: <what should be true after this task>
|
||||
Why: <one sentence>
|
||||
Done when: <measurable acceptance>
|
||||
Out of scope: <things explicitly not to touch>
|
||||
Risks: <what could go wrong>
|
||||
```
|
||||
|
||||
### Per task
|
||||
2. Put the spec at the top of the PR description (draft PR is fine)
|
||||
**before** writing code.
|
||||
3. Reuse the spec as the AI prompt when handing the task off.
|
||||
|
||||
Before starting work that takes more than ~half a day:
|
||||
After the task ships:
|
||||
|
||||
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.
|
||||
- Update the PR description to match what actually shipped (not what
|
||||
was originally proposed).
|
||||
- Lessons future tasks would want → Claude memory (feedback / project
|
||||
types). See [Memory](#memory).
|
||||
|
||||
---
|
||||
|
||||
@@ -789,7 +714,7 @@ Fill it before declaring handoff done.
|
||||
|
||||
## Working directory expectations (this repo)
|
||||
|
||||
- Small repo (~10 files). `Read` everything before acting; no need to
|
||||
spawn a sub-agent for exploration.
|
||||
- This is a small docs-only repo. `Read` everything in scope before
|
||||
acting; don't 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.
|
||||
toolchain files. There is no build/test/lint here.
|
||||
@@ -1,87 +1,54 @@
|
||||
# team-guide
|
||||
|
||||
我们小团队的 AI 协作(vibe coding)开发约定。1–3 人规模,规则不多但都是真踩过的坑。
|
||||
我们小团队的 AI 协作开发约定。**给 AI 看的**——每个项目里 AI 开干前先读这里。
|
||||
|
||||
完整规则在 [`AGENTS.md`](AGENTS.md)(英文,给 AI 看)——本仓库的**唯一规则来源**。
|
||||
这份 README 是给人的导览,知道去哪查、怎么参与就行。
|
||||
完整规则在 [`AGENTS.md`](AGENTS.md)(英文)。这份 README 只是入口说明。
|
||||
|
||||
## 这个仓库给谁用
|
||||
## 这个仓库怎么用
|
||||
|
||||
**给 AI 用**。每个团队项目里 AI 开干前应该先读 team-guide:
|
||||
AI 进任何团队项目前的读取顺序:
|
||||
|
||||
1. 读 [`AGENTS.md`](AGENTS.md)——团队通用规则
|
||||
2. 扫 [`library/README.md`](library/README.md)——按当前任务挑相关条目读
|
||||
3. 再读项目自己的 `AGENTS.md`——只放项目特定的东西
|
||||
1. [`AGENTS.md`](AGENTS.md) —— 团队通用规则
|
||||
2. [`library/README.md`](library/README.md) —— 按当前任务挑相关条目读
|
||||
3. 项目自己的 `AGENTS.md` —— 只放项目特定的东西
|
||||
|
||||
项目自己的 `AGENTS.md` **不重复**这里的规则,引用就行,保持小而具体。
|
||||
|
||||
## 怎么用(人)
|
||||
|
||||
1. **新成员** —— 读这份 README 五分钟,再扫一眼 [AGENTS.md](AGENTS.md) 的目录。具体规则用到再翻。
|
||||
2. **新项目** —— 在新仓库根目录放 `AGENTS.md`(骨架在 [AGENTS.md](AGENTS.md) 的 Claude Code & Codex 节),再放一行 `@AGENTS.md` 的 `CLAUDE.md`。让两边 AI 工具读同一份项目说明。
|
||||
3. **不同意某条规则** —— 在本仓库开 PR 改它,不要私下绕开。
|
||||
项目自己的 `AGENTS.md` **不重复** team-guide 里的内容,引用就行。
|
||||
|
||||
## 语言策略
|
||||
|
||||
- **给人看的(中文)**:本 README。
|
||||
- **给 AI 看的(英文)**:[`AGENTS.md`](AGENTS.md)、[`CLAUDE.md`](CLAUDE.md)、`library/` 下所有内容。
|
||||
- **Git 元数据(英文)**:commit、PR 标题、分支名、tag 注释。
|
||||
|
||||
理由:AI 工具和搜索更吃英文 metadata;规则只需要一份不需要两份;中文给人在入口处看到。
|
||||
- **本 README 中文**——给人读的入口
|
||||
- **AGENTS.md / CLAUDE.md / library/ 全英文**——给 AI 读
|
||||
- **commit、PR 标题、分支名、tag 注释全英文**——AI 工具和搜索吃英文 metadata 更准
|
||||
|
||||
## 目录
|
||||
|
||||
```
|
||||
team-guide/
|
||||
├── README.md ← 你正在看(中文,给人)
|
||||
├── AGENTS.md ← 全部团队规则(英文,给 AI)
|
||||
├── README.md ← 中文入口(你正在看)
|
||||
├── AGENTS.md ← 全部团队规则(英文)
|
||||
├── CLAUDE.md ← 一行 @AGENTS.md import
|
||||
└── library/ ← 窄主题专项规范目录
|
||||
└── library/ ← 窄主题专项规范
|
||||
├── README.md ← catalog
|
||||
└── git-upload/ ← 第一篇:什么该传什么不该传
|
||||
└── SPEC.md
|
||||
└── <topic>/SPEC.md
|
||||
```
|
||||
|
||||
[`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:`YYYYMMDD`,比如 `20260520`。同一天多次发布加 `-N` 后缀(`20260520-2`)。从 `main` 打 tag。
|
||||
本仓库按日期打 tag:`YYYYMMDD`(同一天多次发布加 `-N` 后缀)。tag 不可改、不可删、不可 force-push。
|
||||
|
||||
通用规则:
|
||||
具体规则见 [`AGENTS.md`](AGENTS.md) §3 Git workflow。项目仓库自己用各自的 tag 方案(通常 semver `vX.Y.Z`),写在项目的 `AGENTS.md` 里。
|
||||
|
||||
- `main` 永远是当前工作副本。
|
||||
- 只用 annotated tag(`git tag -a`)。
|
||||
- Tag 一旦推到远端就不能改、不能删、不能 force-push。错了切新的。
|
||||
- 谁要"用某一版",告诉对方 tag 名(`team-guide @ 20260520`)就行。
|
||||
## Library 怎么扩
|
||||
|
||||
项目仓库自己(task_assistant 这类)用各自的 tag 方案(通常是 semver `vX.Y.Z`),写在项目自己的 `AGENTS.md` 里。
|
||||
碰到跨项目的具体话题、塞进 AGENTS.md 会拖肿(比如"PII 处理"、"eval 报告格式"),就在 `library/<topic>/` 下写 `SPEC.md`。
|
||||
|
||||
具体命令和什么时候切 tag——见 [`AGENTS.md`](AGENTS.md) 的 Git workflow 节。
|
||||
收录标准(同时满足):
|
||||
|
||||
## 几条最容易踩的线(速查)
|
||||
1. 至少踩过两次
|
||||
2. 比 AGENTS.md 通用规则窄
|
||||
3. 步骤稳定到能写下来
|
||||
|
||||
完整版在 AGENTS.md 和 library/,这里挑人最常忘的:
|
||||
|
||||
- 长 session 的上下文会污染输出,新任务开新 session
|
||||
- 不读 diff 就 "looks good" 是 bug 上线的标准姿势
|
||||
- 一个 session 不要同时让 Claude Code 和 Codex 改同一个文件
|
||||
- AI 试同一个方案两次报同样的错——叫停,自己上
|
||||
- `git add .` 前先 `git status` 看一眼,确认没有不该传的文件
|
||||
- 提交前 `git diff --cached` 扫一眼;密钥误提交的应急流程在 [`library/git-upload/SPEC.md`](library/git-upload/SPEC.md)
|
||||
加一条要同时更新 [`library/README.md`](library/README.md) 的 catalog 表。
|
||||
|
||||
## 远端
|
||||
|
||||
|
||||
+4
-3
@@ -17,9 +17,10 @@ When starting a non-trivial task:
|
||||
|
||||
## Catalog
|
||||
|
||||
| Entry | Read it when… |
|
||||
| -------------------------------------- | ---------------------------------------------------------- |
|
||||
| [`git-upload/`](git-upload/SPEC.md) | Pushing code to a remote, especially first push or new files |
|
||||
| Entry | Read it when… |
|
||||
| ------------------------------------------- | -------------------------------------------------------------- |
|
||||
| [`git-upload/`](git-upload/SPEC.md) | Pushing code to a remote, especially first push or new files |
|
||||
| [`nodejs-project/`](nodejs-project/SPEC.md) | Working in any Node.js / Next.js project — task execution SOP |
|
||||
|
||||
(More entries will be added as the team encounters recurring questions
|
||||
worth standardizing.)
|
||||
|
||||
@@ -0,0 +1,238 @@
|
||||
# nodejs-project — AI execution SOP
|
||||
|
||||
## When to read this
|
||||
|
||||
- Working in any Node.js / Next.js project (anything with a `package.json`).
|
||||
- Initializing a new Node project.
|
||||
- About to commit, push, or release a Node project.
|
||||
|
||||
This is the AI's task-execution sequence. Each phase is a concrete set
|
||||
of commands or checks the AI runs **on its own** before declaring the
|
||||
task done. The only points that pause for the human are flagged
|
||||
explicitly.
|
||||
|
||||
## Phase 0 — Project entry
|
||||
|
||||
Run on first action in the repo:
|
||||
|
||||
```bash
|
||||
ls AGENTS.md CLAUDE.md package.json .gitignore
|
||||
node --version
|
||||
cat package.json | grep -A 20 '"scripts"'
|
||||
```
|
||||
|
||||
- **No `AGENTS.md`** → stop. Ask the human: "this project has no
|
||||
AGENTS.md; create one before proceeding?"
|
||||
- **No `.gitignore` or it's <100 bytes** → stop. The project is missing
|
||||
basic ignore rules; flag before any commit.
|
||||
- **`node --version` doesn't match what AGENTS.md says** → stop, ask.
|
||||
|
||||
## Phase 1 — Task framing
|
||||
|
||||
Trigger conditions, in order:
|
||||
|
||||
- Task description < 3 sentences AND scope > 1 file → ask for the
|
||||
5-line spec (`Goal / Why / Done when / Out of scope / Risks`).
|
||||
- Task touches: `package.json` deps, schema, auth, secrets, production
|
||||
config, build scripts → confirm scope with human before any edit.
|
||||
- Otherwise: write the implicit spec into the PR description draft and
|
||||
proceed.
|
||||
|
||||
## Phase 2 — Pre-edit sync
|
||||
|
||||
```bash
|
||||
git status # working tree clean?
|
||||
git pull --ff-only # remote ahead?
|
||||
```
|
||||
|
||||
- Working tree dirty with unrelated changes → stop, ask.
|
||||
- `pull --ff-only` fails (diverged history) → stop, ask. Don't
|
||||
force-pull, don't merge silently.
|
||||
|
||||
## Phase 3 — Edit & verify
|
||||
|
||||
After each meaningful change run:
|
||||
|
||||
```bash
|
||||
npm run check # if defined
|
||||
npm test # if defined
|
||||
npx tsc --noEmit # for TypeScript / Next.js
|
||||
```
|
||||
|
||||
For projects with `build-release` or similar build scripts: do **not**
|
||||
run them automatically — they produce large artifacts. Run only when
|
||||
the task is "release."
|
||||
|
||||
Failure handling:
|
||||
|
||||
- Fix the error, re-run.
|
||||
- **Same error twice** → stop, surface to human. Don't keep retrying.
|
||||
|
||||
## Phase 4 — Encoding & line-ending checks
|
||||
|
||||
Run before staging any text file changes. Source code on this team is
|
||||
**UTF-8 without BOM**, line endings follow the project's existing
|
||||
convention (typically LF, except `.bat` / `.cmd` which need CRLF).
|
||||
|
||||
Detection commands:
|
||||
|
||||
```bash
|
||||
# Find files with UTF-8 BOM (EF BB BF) — should be empty output
|
||||
git diff --cached --name-only -z | xargs -0 -I{} sh -c \
|
||||
'head -c 3 "{}" | od -An -tx1 | grep -q "ef bb bf" && echo "BOM: {}"'
|
||||
|
||||
# Find CRLF in source files that should be LF (skip .bat/.cmd)
|
||||
git diff --cached --name-only -z | xargs -0 grep -lI $'\r' 2>/dev/null \
|
||||
| grep -vE '\.(bat|cmd)$'
|
||||
|
||||
# Find non-UTF-8 bytes in source
|
||||
git diff --cached --name-only -z | xargs -0 -I{} sh -c \
|
||||
'iconv -f UTF-8 -t UTF-8 "{}" >/dev/null 2>&1 || echo "non-UTF8: {}"'
|
||||
```
|
||||
|
||||
Hits → fix before commit:
|
||||
|
||||
- BOM in `.js` / `.mjs` / `.json` / `.md` / `.html` / `.css` → strip.
|
||||
Node `JSON.parse` rejects BOM in `package.json`. Some bundlers ship
|
||||
BOM into the output and break browsers.
|
||||
- CRLF in `.js` / `.mjs` / `.ts` / `.tsx` / `.json` / `.md` / `.sh` →
|
||||
convert to LF. CRLF in `.sh` makes the script silently fail on Linux.
|
||||
- CRLF in `.bat` / `.cmd` → keep, this is correct.
|
||||
- Non-UTF-8 bytes (typically GBK on Windows) → re-save the file as
|
||||
UTF-8 in the editor. This is the most common silent corruption when
|
||||
AI edits a Chinese-content file on a system with Windows-default
|
||||
encoding — symptom is "好" appearing as "濂" or similar mojibake.
|
||||
|
||||
Editor / tool notes for the human:
|
||||
|
||||
- Set editor to UTF-8 default and save without BOM.
|
||||
- VSCode: status bar bottom-right shows current file's encoding;
|
||||
click to "Save with Encoding → UTF-8" if needed.
|
||||
- `.gitattributes` baseline (commit it once per project):
|
||||
|
||||
```
|
||||
* text=auto eol=lf
|
||||
*.bat text eol=crlf
|
||||
*.cmd text eol=crlf
|
||||
*.png binary
|
||||
*.jpg binary
|
||||
*.zip binary
|
||||
```
|
||||
|
||||
This forces normalization on commit and prevents future drift.
|
||||
|
||||
## Phase 5 — Pre-commit verification
|
||||
|
||||
```bash
|
||||
git status
|
||||
git diff --cached
|
||||
```
|
||||
|
||||
The AI must read the entire `--cached` diff and answer in its own
|
||||
output:
|
||||
|
||||
1. Build / typecheck pass?
|
||||
2. Tests pass (or honestly: "didn't run because <reason>")?
|
||||
3. Files outside the stated scope? List + justify each, or revert.
|
||||
4. New deps? List them in PR description and Phase 1 confirmation.
|
||||
5. AI-generated comments restating the code? Delete.
|
||||
6. End-to-end exercised (for user-visible changes)?
|
||||
|
||||
Plus **Node-specific Phase 5 checks**:
|
||||
|
||||
- `package-lock.json` in diff but no change to `package.json` deps →
|
||||
stop. This is usually IDE auto-install. Revert the lockfile diff.
|
||||
- `package.json` deps changed but no lockfile diff → stop. Run
|
||||
`npm install` once, commit lockfile in same commit.
|
||||
- `.env` / `.env.local` / `.env.production` / `*.pem` / `*.key` in diff
|
||||
→ **stop, do not commit**. Add to `.gitignore` if missing.
|
||||
- `node_modules/` / `.next/` / `dist/` / `build/` / `out/` in diff →
|
||||
stop. Gitignore is broken; fix before commit.
|
||||
- Files >5 MB in diff (`git diff --cached --stat | awk '$3 > 5120'`) →
|
||||
stop, ask human about LFS or out-of-band delivery.
|
||||
- Any encoding hit from Phase 4 unresolved → stop.
|
||||
|
||||
## Phase 6 — Commit
|
||||
|
||||
```bash
|
||||
git add <specific files> # NOT git add . / git add -A
|
||||
git commit -m "<area>: <imperative summary under 60 chars>"
|
||||
```
|
||||
|
||||
- Always include `Co-Authored-By: Claude <noreply@anthropic.com>` (or
|
||||
the project's tool-specific trailer) for AI-assisted commits.
|
||||
- One topic per commit. "and" in summary → split.
|
||||
- English message.
|
||||
|
||||
## Phase 7 — Push
|
||||
|
||||
```bash
|
||||
git push origin <branch>
|
||||
```
|
||||
|
||||
- First push of a new feature branch: include `-u`.
|
||||
- Branch is `main` or `dev` → **stop, ask human** before push.
|
||||
- `--force` push → **stop, ask human**, regardless of branch. Quote the
|
||||
reason and the branch back to the human.
|
||||
|
||||
## Phase 8 — Release (product projects only)
|
||||
|
||||
Only run when the task is explicitly "release vX.Y.Z." Skip otherwise.
|
||||
|
||||
```bash
|
||||
# 1. Read project's AGENTS.md "release-bump checklist"
|
||||
# 2. For each listed file: edit, then verify no stale version remains
|
||||
git grep -nE 'V?[0-9]+\.[0-9]+\.[0-9]+' -- <changed-files>
|
||||
|
||||
# 3. Standard checks
|
||||
npm run check
|
||||
npm test
|
||||
|
||||
# 4. Commit + tag
|
||||
git add <changed files>
|
||||
git commit -m "chore: release vX.Y.Z"
|
||||
git tag -a vX.Y.Z HEAD -m "<Project> VX.Y.Z"
|
||||
git push origin <branch>
|
||||
git push origin vX.Y.Z
|
||||
|
||||
# 5. Build
|
||||
npm run release # or project's build script
|
||||
|
||||
# 6. List artifacts
|
||||
ls -lh release/ # or wherever the build outputs
|
||||
|
||||
# 7. STOP — ask human:
|
||||
# "Artifacts ready: <list>. Sizes: <sizes>. Upload to <distribution
|
||||
# channel>?"
|
||||
```
|
||||
|
||||
The upload step is **always human-confirmed**. It's the only
|
||||
externally-visible irreversible action in the flow.
|
||||
|
||||
## Where the human pauses
|
||||
|
||||
In total, AI stops and asks the human only at:
|
||||
|
||||
- Phase 0: missing AGENTS.md
|
||||
- Phase 1: vague task or scope-sensitive change
|
||||
- Phase 2: dirty tree or diverged history
|
||||
- Phase 3: same error twice
|
||||
- Phase 4 / 5: encoding / lockfile / secret / large-file anomalies
|
||||
- Phase 7: push to `main`/`dev` or `--force`
|
||||
- Phase 8: distribution upload
|
||||
|
||||
Everything else is self-running.
|
||||
|
||||
## Quick reference (for AI to scan)
|
||||
|
||||
```
|
||||
[entry] read AGENTS.md → no? stop.
|
||||
[frame] vague task? → spec. scope-sensitive? → confirm.
|
||||
[sync] git status / pull --ff-only.
|
||||
[edit] npm run check / test / tsc. fail twice? stop.
|
||||
[encode] no BOM / LF for src / CRLF for .bat / valid UTF-8.
|
||||
[verify] git diff --cached → 6 questions + Node-specific 5.
|
||||
[commit] git add by name. <area>: <imperative>.
|
||||
[push] main/dev/force? stop. else push.
|
||||
[release] follow project's bump checklist. STOP before upload.
|
||||
```
|
||||
Reference in new issue
Block a user