7 Commits
Author SHA1 Message Date
阿白叔andClaude Opus 4.7 4fa489691f docs: switch plugin install to token-embedded URL
simgreek org requires login for git access, so anonymous /plugin
marketplace add fails. Members generate a Gitea access token (read-only
on repository) and embed it in the plugin URL. Token is stored in
Claude Code settings — documented as a caveat with revocation guidance.

Verified: token-embedded clone over HTTPS retrieves all .claude-plugin
manifest files and skills/.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-25 18:17:09 +08:00
阿白叔andClaude Opus 4.7 ea1819f1d2 feat: rename to praxis, package as Claude Code plugin
Reframe team-guide as praxis (Greek for "practice"): Simgreek's coding
agent rulebook, distributed as a Claude Code plugin so SessionStart
hook can force-inject the using-praxis bootstrap.

- Add .claude-plugin/{marketplace,plugin}.json: makes this repo a
  one-plugin marketplace installable via /plugin marketplace add.
- Add hooks/{hooks.json,session-start,run-hook.cmd}: SessionStart
  hook reads using-praxis SKILL.md and injects it into context as
  hookSpecificOutput.additionalContext (Claude Code) or
  additional_context (Cursor) or additionalContext (Copilot CLI).
- Migrate library/<topic>/SPEC.md → skills/<topic>/SKILL.md with
  YAML frontmatter (name + when-to-invoke description).
- Add skills/using-praxis: bootstrap with iron law, red-flags table,
  catalog, instruction priority, sub-agent stop, Codex/Cursor fallback.
- Add skills/debugging: 4-phase root-cause investigation with
  3-fixes-failed → architectural problem rule.
- Add skills/verification: evidence-before-claims gate with
  rationalization table.
- Drop library/, references in AGENTS.md updated to skills/.
- Rename throughout: team-guide → praxis.
- README rewritten with both install paths (plugin / external spec)
  and updated bootstrap prompt.

Codex / Cursor / non-Claude users still get the spec by reading
AGENTS.md and skills/ files manually — only the auto-injection
requires Claude Code.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-25 18:02:48 +08:00
阿白叔andClaude Opus 4.7 161559a83d docs: add new-project bootstrap prompt to README
Add a copy-pasteable prompt for humans to drop into Claude Code /
Codex when starting a new project. The prompt makes the AI fetch
team-guide, ask consolidated questions, scaffold project files
(AGENTS.md, CLAUDE.md, .gitignore, .gitattributes, .env.example,
README.md), and stop for confirmation before first commit.

Also covers the existing-project case (补规范) by swapping the
scaffolding step.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-21 13:15:40 +08:00
阿白叔andClaude Opus 4.7 17671b2b22 docs: add library/nodejs-project SOP with encoding checks
8-phase AI execution sequence for Node.js / Next.js projects:
entry → frame → sync → edit → encoding → verify → commit → push
→ release. Phase 4 covers BOM / CRLF / non-UTF-8 detection and
fixes — these are the most common silent corruption when AI edits
files on Windows-default encoding systems.

- library/nodejs-project/SPEC.md (new)
- library/README.md catalog updated
- AGENTS.md §5 Team library entry list updated

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-21 12:31:14 +08:00
阿白叔andClaude Opus 4.7 c8ce92a2ed docs: refocus on AI behavior, drop human-only sections
team-guide is for AI to read at task start. Removed sections that
only describe human ceremonies and rewrote rules so AI can act on
them directly.

AGENTS.md:
- Replace §6 Planning cadence (Weekly/Quarterly/anti-Jira rhetoric)
  with §6 Per-task spec — the only planning rule AI actually executes.
- §1 Vibe coding rewritten to be AI-actionable: explicit spec
  requirement, observable stop-conditions (300-line / 5-file
  thresholds), self-verification 6 steps phrased as AI behaviors.
- §2 Claude Code & Codex config compressed: each rule = decision +
  one-line rationale, removed prose around skills/memory/sub-agents.
- §3 Git: drop branch owner-prefix rule, draft-PR rhythm, comment
  etiquette. Keep PR description structure and reviewer 5-step.
  Tag examples use <YYYYMMDD> placeholder so AI doesn't anchor on
  a specific date.
- §Editing rules: drop snark ("No 🚀 Getting started! energy") that
  could be misread; plain "No emoji".
- §Working directory: remove hardcoded "~10 files" count.

README.md:
- Drop "速查" cheatsheet (was for humans, redundant with AGENTS.md).
- Drop hardcoded tag examples (20260520).
- Trim positioning explanation in half.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-21 11:52:53 +08:00
阿白叔andClaude Opus 4.7 c5e6ebb534 docs: replace templates/ with library/, drop unaudited Product section
team-guide is now positioned as the external rulebook agents read at
project start: project AGENTS.md files reference team-guide rather
than duplicating its content.

- Delete templates/ (5 files). The only useful one — AGENTS.md
  skeleton — is now an inline code block in AGENTS.md §2. Handoff
  checklist also inlined into AGENTS.md §7.
- Remove the unaudited "Product projects" section (was AGENTS.md §5).
  Project repos document their own release scheme in their own
  AGENTS.md.
- Add library/ as a catalog for narrower specs.
- Seed library/git-upload/SPEC.md: what to commit / what not to,
  .gitignore baseline, sensitive-info scan, leaked-secret recovery.
- AGENTS.md gets a "How AI agents use this repo" intro and a §5 Team
  library section indexing library/.
- README.md updated to match: explicit "for AI" framing, library
  section, drop product-spec mentions.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 23:38:46 +08:00
阿白叔andClaude Opus 4.7 94eb7ef70a docs: collapse docs/ into single AGENTS.md, slim README
Single source of truth for AI is AGENTS.md. CLAUDE.md becomes a
one-line @AGENTS.md import so Claude Code and Codex read the same
spec — zero drift. README.md becomes a short Chinese entry point
(language policy, layout, tag styles, top pitfalls) and links into
AGENTS.md for full rules.

- Consolidate docs/01-08 into AGENTS.md (7 sections, ~700 lines)
- README.md: ~80-line Chinese entry point, no rule duplication
- CLAUDE.md: just "@AGENTS.md"
- Delete docs/ — content preserved in git history at tag 20260520-3

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 16:56:19 +08:00
26 changed files with 1941 additions and 1620 deletions

No files matched your search

+20
View File
@@ -0,0 +1,20 @@
{
"name": "praxis",
"description": "Simgreek team's coding agent SOP marketplace.",
"owner": {
"name": "Simgreek",
"url": "https://git.simgreek.com/simgreek"
},
"plugins": [
{
"name": "praxis",
"description": "Simgreek team's AI coding agent rulebook: SOP for Node.js projects, git hygiene, debugging, verification.",
"version": "0.1.0",
"source": "./",
"author": {
"name": "Simgreek",
"url": "https://git.simgreek.com/simgreek"
}
}
]
}
+20
View File
@@ -0,0 +1,20 @@
{
"name": "praxis",
"description": "Simgreek team's AI coding agent rulebook: SOP for Node.js projects, git hygiene, debugging, verification — practice over theory.",
"version": "0.1.0",
"author": {
"name": "Simgreek",
"url": "https://git.simgreek.com/simgreek"
},
"homepage": "https://git.simgreek.com/simgreek/praxis",
"repository": "https://git.simgreek.com/simgreek/praxis",
"license": "Internal",
"keywords": [
"skills",
"sop",
"nodejs",
"git",
"debugging",
"team-rules"
]
}
+711 -77
View File
@@ -1,103 +1,737 @@
# AGENTS.md — team-guide
# AGENTS.md — praxis
Context for AI coding agents (Codex CLI, Codex in IDEs, other
AGENTS.md-aware tools) working in this repository.
Working agreements for the Simgreek team's AI-assisted development.
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.
> 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.
If installed as a Claude Code plugin (`/plugin install praxis`), the
`SessionStart` hook also injects the `using-praxis` skill into the
session — see [`skills/using-praxis/SKILL.md`](skills/using-praxis/SKILL.md).
> Human-facing entry point: [`README.md`](README.md) (Chinese,
> condensed). When humans want the full ruleset, they read this file.
## How AI agents use this repo
Before starting non-trivial work in any team project, an agent should:
1. **Read this `AGENTS.md`** — general rules (vibe coding, Git, code
style, planning, handoff).
2. **Scan [`skills/`](skills/)** — narrower SOPs. The
[`using-praxis` skill](skills/using-praxis/SKILL.md) lists the full
catalog and tells you when to invoke each.
3. **Read the project's own `AGENTS.md`** — project-specific stuff
(how to run it, architecture, project-only don'ts). Project AGENTS.md
files do **not** repeat praxis content; they reference it.
In short: praxis is the external rulebook every project's agent reads
at task start. Project AGENTS.md files stay small and specific.
## Project
This repo holds our team's working agreements (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.
- 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.
when the rule isn't self-evident.
- No emoji.
- Keep AGENTS.md under ~600 lines. Past that, split a section into
`skills/`.
- 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`,
`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.
- **Human-facing**: Chinese — `README.md` only.
- **AI-facing**: English — this file, `CLAUDE.md`, anything under
`skills/`.
- **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: `<area>: <imperative summary under 60 chars>`. 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<x.y.z>`. 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).
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.
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
toolchain files unless explicitly asked. This is a docs repo.
**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
- Stop AI when it's tried twice and is going in circles
- Sign off on commit messages and PR descriptions (AI drafts; human signs)
### Spec requirement
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:
```
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>
```
Don't infer the spec silently. Vague task + silent inference is the most
common cause of AI rework.
### Prompt habits (rules for human input that improve AI output)
- **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 AI must stop and surface to the human
AI stops driving and surfaces the situation to the human when:
- 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).
In each case, AI summarizes the situation and asks for direction. Don't
keep iterating.
### Output verification (AI runs this on its own diffs before declaring done)
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.
---
## 2. Claude Code & Codex configuration
### Per-project files
```
<repo>/
├── 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.
### Per-project AGENTS.md content
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).
Past 100 lines → split. Skeleton:
```markdown
# AGENTS.md — <project name>
> Reference: praxis for cross-project rules. This file holds only
> what's specific to this project.
## Project
<one or two sentences>
## Run it
```bash
<install / run / test / lint commands>
```
## Architecture
<one paragraph: entry points, data flow, major modules>
Key files:
- `<path>` — <one-line role>
## Conventions specific to this repo
<naming patterns, where to add new features, what's auto-generated>
## Don'ts
- Don't <…>
```
`CLAUDE.md` in a new project is one line: `@AGENTS.md`.
### Permissions (Claude Code)
Default: prompt for risky, allow read-only. **Why:** keeps friction
low for safe ops while preserving review of mutations.
Allow without prompt: all `Read`/`Glob`/`Grep`, read-only Bash
(`git status`, `git diff`, `git log`, `git branch`, project test
runners).
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`. **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
AI does not reliably remember "from now on do X" across sessions —
hooks enforce automatically.
Use for: auto-format on edit, block writes to protected paths
(`.env`, generated files, `dist/`), auto-test after writing test files,
session-stop notifications.
Don't use for: one-off reminders, anything depending on AI judgment.
### Memory
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).
Memory is personal and per-machine — never substitute for AGENTS.md.
Task-scoped state goes in plans or PR descriptions, not memory.
### Skills
Locations: user (`~/.claude/skills/`), project
(`<repo>/.claude/skills/`), plugin marketplace.
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`), not nouns
(`pr-helper`).
- Description tells the model **when to invoke**, not what the skill
does.
- `SKILL.md` under 200 lines.
Recommended installs (read each skill's own description for what it
does):
```
consolidate-memory simplify fewer-permission-prompts review security-review
```
### Sub-agents
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.
### Mixing Claude Code + Codex
Both fine. **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.
---
## 3. Git workflow
### Branches
- `main` (spec repos) / `dev` (product repos) is always shippable. No
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
```
<area>: <imperative summary under 60 chars>
<optional body — what changed and why, not how>
```
- `<area>` is a directory or component, lowercase.
- Imperative: "add", "fix", "rename" — not "added" / "adding".
- 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 structure: **Summary** (1 sentence + bullets if needed) /
**Why** / **What changed** (bulleted by file or area) / **Test plan**
(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`.
### Review (when AI is reviewer)
When AI reviews a PR, run these checks in order:
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.
- Final squash message follows commit format.
- Delete the branch on merge.
### Tagging (this repo)
Tags are dated: `<YYYYMMDD>`, with `-N` suffix for same-day reissues
(e.g. `<YYYYMMDD>-2`). Tag from `main`.
Rules:
- Annotated only (`git tag -a`).
- Tag message summarizes what changed since the previous tag.
- Tags are immutable once pushed. Wrong tag → cut a new one.
- Don't tag on feature branches.
- Max one tag per day; use `-N` for same-day reissues.
Cut a tag:
```bash
git checkout main && git pull --ff-only
git tag -a <YYYYMMDD> -m "praxis <YYYYMMDD>: <summary>"
git push origin <YYYYMMDD>
```
Inspect:
```bash
git tag --sort=-creatordate
git show <YYYYMMDD>
git log --oneline <prev-tag>..<this-tag>
```
When to cut a tag:
- Rules changed in a way that affects how AI should behave on tasks.
- A skill was added, removed, or restructured.
When **not** to cut a tag:
- Typos, formatting, link fixes → just push to `main`.
- Drafts under discussion → use a PR.
Project repos in the workspace use their own tag schemes (typically
semver `vX.Y.Z`). Each project documents its own scheme in its own
`AGENTS.md`.
### Don'ts
- 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 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.
---
## 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.
Shorter than this is fine — drop sections that don't apply.
### 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. Skills catalog
Narrower SOPs live under [`skills/`](skills/). Each `SKILL.md` has a
YAML `description` frontmatter telling the AI **when to invoke it**.
The `using-praxis` skill is the bootstrap — read it first; it lists the
catalog with full triggering criteria.
Current skills:
- [`skills/using-praxis/`](skills/using-praxis/SKILL.md) — bootstrap,
iron-law / red-flags / catalog. Loaded automatically by the
`SessionStart` hook when the praxis plugin is installed.
- [`skills/git-upload/`](skills/git-upload/SKILL.md) — what to commit,
what not to, how to recover from leaked secrets.
- [`skills/nodejs-project/`](skills/nodejs-project/SKILL.md) — task
execution SOP for Node.js / Next.js projects (8 phases, includes
encoding checks).
- [`skills/debugging/`](skills/debugging/SKILL.md) — root-cause
investigation before any fix; 4-phase process.
- [`skills/verification/`](skills/verification/SKILL.md) — evidence
before completion claims.
A skill graduates from "this seems like a good idea" to a real entry
when **all three** hold:
1. Done the same way 3+ times.
2. Steps stable enough to write down.
3. Someone else would do it the same way given the spec.
Skill design rules: one skill, one job; verb-phrase name; description
field tells the model **when to invoke**, not what the skill does;
under ~300 lines.
---
## 6. Per-task spec
Before AI writes code on a task that touches more than one file:
1. Confirm or produce a 5-line spec.
```
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>
```
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.
After the task ships:
- 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).
---
## 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 the [handoff checklist](#handoff-checklist) below. External has
higher bar.
### Task package layout
```
<package>/
├── 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": "<full sha>",
"source_repo": "<git remote url>",
"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.
### Handoff checklist
Copy into the package (external handoff) or PR description (internal).
Fill it before declaring handoff done.
```markdown
## Identity
- Name:
- Version: <e.g. v0.5.0 or commit sha or tag>
- Generated at: <ISO timestamp>
- Source repo:
- Source commit: <full sha>
- Owner: <name>
- Recipient: <name or team>
## Contents
- [ ] README.md — what this is, how to use it
- [ ] CHANGELOG.md — diff vs previous version (or "first release")
- [ ] manifest.json — all fields filled or explicitly null
- [ ] VERIFICATION.md — what was checked, results
- [ ] Data / artifacts
- [ ] Scripts (only what's required to use the package)
## Verification
- [ ] Record / file counts match expected
- [ ] Checksums computed and recorded
- [ ] Sanity checks pass (list them)
- [ ] No secrets, .env, or credentials
- [ ] No PII unless explicitly part of deliverable
- [ ] Total size reasonable for delivery channel
## Reproducibility (external handoff only)
- [ ] Confirmed someone with repo access can rebuild from source_commit
- [ ] Build / generation command documented in README.md
- [ ] External dependencies pinned
## Provenance (if AI-assisted)
- Model used:
- Human-in-loop steps:
- Notable AI-assisted decisions:
## Known limitations
- <…>
## Recipient instructions
- [ ] Read README.md first
- [ ] Run verification report; if fails, stop and contact sender
- [ ] Confirm receipt within <X days>
- [ ] Report any surprises within <X days>
```
---
## Working directory expectations (this repo)
- 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. There is no build/test/lint here.
+1 -109
View File
@@ -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: `<area>: <imperative summary under 60 chars>`. 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<x.y.z>`. 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
+115 -63
View File
@@ -1,87 +1,139 @@
# team-guide
# praxis
我们小团队的 AI 协作(vibe coding)开发约定。
1–3 人规模,规则不多但都是真踩过的坑。
Simgreek 团队的 AI 协作开发约定。**给 AI 看的**——每个项目里 AI 开干前先读这里。
## 这个仓库是什么
完整规则在 [`AGENTS.md`](AGENTS.md)(英文)。skill 库在 [`skills/`](skills/)。这份 README 是给人的入口说明。
工作方式的唯一来源——不是项目代码,是**怎么干活**。覆盖:
## praxis 是什么
- 怎么用 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 这类有版本、有发行包的)的设计与发版规范
源自希腊语 *praxis*(实践)。Simgreek 团队的"踩过坑就写下来"的总和,给 AI agent 用。
每篇都很短。一条规则要超过半页才能解释清楚的,多半还不是规则——是个待讨论项。
两种用法:
- **作为 Claude Code 插件**(推荐)—— `/plugin install praxis` 之后,session 一开 hook 就把 `using-praxis` 强制注入 context,AI 行为受铁律约束。
- **作为外部规范**—— 不装插件也能用:AI 进项目前读 `AGENTS.md` + 扫 `skills/`,靠自觉调用。Codex / Cursor 走这条。
## 安装(Claude Code 插件)
simgreek 仓库要求登录访问,所以 plugin URL 里要带个人 access token。每个团队成员一次性配一下。
**第 1 步**:在 Gitea 生成 token
登录 [git.simgreek.com](https://git.simgreek.com) → 右上角头像 → Settings → Applications → 「Manage Access Tokens」 → 生成一个新 token:
- Token 名字:`claude-code-plugin`(或你喜欢的)
- 权限只勾 `repository: read` 就够,越小越好
- **生成后立刻复制保存**——离开页面就看不到了
**第 2 步**:在 Claude Code 装
把下面的 `<YOUR_USERNAME>` 和 `<YOUR_TOKEN>` 替换掉:
```
/plugin marketplace add https://<YOUR_USERNAME>:<YOUR_TOKEN>@git.simgreek.com/simgreek/praxis
/plugin install praxis
```
装完之后每次开新 session,praxis 的 `SessionStart` hook 会把 `using-praxis` 内容直接灌进 system context——AI 在做任何事之前都会读到铁律和 red flags。
**安全提醒**:
- token 会被 Claude Code 写进本地 settings——别让别人翻你电脑,也别把 settings 文件分享出去
- token 不要提交进任何仓库
- 共用电脑 / 临时机器装完用完,去 Gitea token 页面 revoke 掉
- token 失效或换了,重新跑 `/plugin marketplace add` 用新 URL
升级:`/plugin update praxis`(自动用同一个 token 拉新版本)
卸载:`/plugin uninstall praxis`
## 不装插件怎么用
把这段提示词丢给 AI 当首句话:
```text
请按以下顺序为本项目做初始化或推进任务:
1. 拉取并阅读 https://git.simgreek.com/simgreek/praxis 的最新内容
(至少读 AGENTS.md 和 skills/using-praxis/SKILL.md,再扫 skills/
下的其他 SKILL.md,匹配当前任务的读完)。
2. 读完后,如果是新项目初始化,问我以下信息(一次性问完):
- 项目名 / 一句话定位
- 技术栈(Node 版本、是否 Next.js / Express / 其他)
- 远端仓库地址(gitee / git.simgreek.com / 其他)
- 协作主分支名(main / dev)
- 是否产品项目(要发分发渠道);是的话,分发渠道是什么
- 需要哪些环境变量(只要变量名,不要值)
3. 拿到回答后,按 praxis 的规范:
- git init(如果还没)+ 配 .gitignore(含 node_modules / .env*
/ 构建产物 / .claude/settings.local.json 等)
- 落 .gitattributes(强制 LF,.bat/.cmd 用 CRLF,二进制标 binary)
- 写 .env.example(仅变量名)
- 写项目根 AGENTS.md,遵循 praxis AGENTS.md §2 的骨架,引用 praxis
而不是复制规则
- CLAUDE.md 写一行:@AGENTS.md
- 写 README.md(中文,给人看,三段:是什么 / 怎么跑 / 怎么配 .env)
4. 全部建好后列出改动,等我确认再 commit。第一个 commit 不直接 push。
5. 整个过程严格遵守 praxis 的「AI 必须停下问人」规则——任务模糊、
范围敏感、远端冲突、--force、上传分发渠道,这些必须停下来确认。
```
老项目补规范,把第 3 步换成"补齐缺失的文件,不要覆盖现有的内容;冲突先列出来问我"。
## 语言策略
- **给人看的**:中文。`README.md`、`docs/*.md`、人填的 template
(README、PR、handoff)都是中文。
- **给 AI 看的**:英文。`CLAUDE.md`、`AGENTS.md`、对应 template、
以及中文文档里的代码块 / 命令示例。
- **Commit / PR / 分支 / tag**:英文。AI 工具和搜索都更吃英文 metadata。
- **本 README 中文**——给人读的入口
- **AGENTS.md / CLAUDE.md / skills/ 全英文**——给 AI 读
- **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 ← 给人填(中文)
praxis/
├── README.md ← 中文入口(你正在看)
├── AGENTS.md ← 全部团队规则(英文)
├── CLAUDE.md ← 一行 @AGENTS.md import
├── .claude-plugin/ ← Claude Code 插件元数据
│ ├── marketplace.json
│ └── plugin.json
├── hooks/ ← SessionStart hook,强制注入 using-praxis
│ ├── hooks.json
│ ├── session-start
│ └── run-hook.cmd
└── skills/ ← AI 行为约束
├── using-praxis/ ← bootstrap:铁律 / red flags / 目录
├── git-upload/ ← 该传 / 不该传 / 泄密恢复
├── nodejs-project/ ← Node 项目 8 阶段执行 SOP(含编码检查)
├── debugging/ ← 4 阶段根因调查
└── verification/ ← 完成前必须有证据
```
## 怎么用
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 改它,不要私下绕开。
## 版本管理
按**项目类型**分两种 tag 风格:
本仓库按日期打 tag:`YYYYMMDD`(同一天多次发布加 `-N` 后缀)。tag 不可改、不可删、不可 force-push。
- **规范类**(本仓库 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)。
具体规则见 [`AGENTS.md`](AGENTS.md) §3 Git workflow。项目仓库自己用各自的 tag 方案(通常 semver `vX.Y.Z`),写在项目的 `AGENTS.md` 里。
通用规则:
## Skill 怎么扩
- `main`(规范类)/ `dev`(产品类)永远是当前工作副本,随时合并。
- Tag 一旦推到远端就不能改、不能删、不能 force-push。
- 大改写新 tag,不动旧 tag。
- 谁要"用某一版",告诉对方 tag 名(例:`team-guide @ 20260520`、
`task_assistant @ v0.2.4`)就行。
碰到跨项目的具体话题、塞进 AGENTS.md 会拖肿(比如"PII 处理"、"eval 报告格式"),就在 `skills/<topic>/` 下写 `SKILL.md`。
打 tag 的具体命令和场景见 [`docs/03-git-workflow.md`](docs/03-git-workflow.md)
的 Tag 一节。
收录标准(同时满足):
最近 tag 列表:[git.simgreek.com/simgreek/team-guide/tags](https://git.simgreek.com/simgreek/team-guide/tags)
1. 至少踩过两次
2. 比 AGENTS.md 通用规则窄
3. 步骤稳定到能写下来
新加的 skill 要同时更新 AGENTS.md §5 Skills catalog 和 `using-praxis/SKILL.md` 的目录表。
## 远端
[git.simgreek.com/simgreek/praxis](https://git.simgreek.com/simgreek/praxis) ·
[tags 列表](https://git.simgreek.com/simgreek/praxis/tags)
## License
-77
View File
@@ -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 想"既然来了顺便重构一下"——拒绝。开新任务。
-122
View File
@@ -1,122 +0,0 @@
# 02 — Claude Code
我们在每个项目里怎么配置和使用 Claude Code。
## 配置文件
每个项目应该有:
```
<repo>/
├── 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/`)—— 装一次到处可用
- **项目级**(`<repo>/.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 拉回来做新主题。陈旧上下文会
渗进来。
-153
View File
@@ -1,153 +0,0 @@
# 03 — Git 工作流
小团队,流程从轻。分支、commit、PR、review、tag。
## 分支
- `main` 永远可发。不直接 push,没有例外。
- 功能分支:`<owner>/<short-slug>` —— 比如 `bai/auth-retry`、
`bai/eval-agent-rerun`。小写、连字符、你的 handle 做前缀。
- 长期集成分支:`integration/<topic>` —— 团队同意才用。
- 合并完删分支。老分支会污染搜索结果。
## Commit
格式:
```
<area>: <祈使句小结,60 字符以内>
<可选 body —— 写改了什么、为什么,不写怎么改>
```
- `<area>` 是目录或组件,小写:`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 留到最后,让它明显是闸门。
作者收尾:
- 每条评论都回应,哪怕只是"同意,已在 <commit> 修"。
- 不同意写出来 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 用 `<Project> V<x.y.z>`——细则见
[`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 <remote> dev
git tag -a v0.2.4 HEAD -m "<Project> V0.2.4"
git push <remote> 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`。
按文件名加。
-101
View File
@@ -1,101 +0,0 @@
# 04 — Skill 与规划
我们怎么管 skill 目录、小团队怎么排活。
## Skill 目录
"Skill"是 Claude Code 能调用的、命名好的可复用流程。我们维护三份:
- **个人**(`~/.claude/skills/`)—— 私人,每人自己管。
- **团队**(`<repo>/.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 说明在做错的东西。
- 不是状态秀。周一帖是为了发现卡点,不是证明你干了活。
-96
View File
@@ -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. 文件名带版本:`<name>-v<n>.<ext>` 或 `<name>-<YYYYMMDD>.<ext>`。
一个项目一种约定,定了别变。
2. 配 `README` 写明 schema、生成日期、已知限制。
3. 配验证报告(计数、checksum、合理性检查),跟交付物一起打包。
4. 生成它的 commit hash 写进 README。
完整 checklist 见 [docs/06-handoff.md](06-handoff.md)。
## 不要做的事
- 不要引入第三种做某件事的方式——已经有两种了。挑一种统一。
- 不要"为了灵活性"加配置开关,没有真实用例就别加。YAGNI。
- 不要在功能 PR 里顺手重构无关代码。开新 PR。
- 不要没量就先优化。"可能慢"不是测量结果。
-103
View File
@@ -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`)必须包含:
```
<package>/
├── 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": "<full sha>",
"source_repo": "<git remote url>",
"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 用。
-114
View File
@@ -1,114 +0,0 @@
# 07 — Codex
我们怎么在团队里用 Codex(CLI 与 IDE 集成),以及 `AGENTS.md` 怎么写。
## 为什么要规范
Codex 不读 `CLAUDE.md`。Claude Code 默认不读 `AGENTS.md`。两个工具在
同一个仓库里干活,看的是不同的"项目说明书"。如果只写一份,另一边就
是裸奔。
我们的做法:**两份都写,内容保持同步**。哪边的工具进来读哪边的文件。
## 文件分工
```
<repo>/
├── 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 "<prompt>"`(一次性
任务)。在仓库根目录启动,让它能找到 `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`。
-291
View File
@@ -1,291 +0,0 @@
# 08 — 产品类项目规范
把 task_assistant 这类**有版本、有发行包、有用户使用**的项目从设计
到发布要遵循的约定写下来。规范性文件(像本仓库 team-guide 自己)按
日期 tag;产品代码按 semver。
## 两类项目的分界
| 维度 | 规范类(team-guide、规约文档) | 产品类(task_assistant、authoring-tool) |
| ---------- | ----------------------------- | ---------------------------------------- |
| 内容 | 文档、约定、模板 | 可执行代码、可发行的产物 |
| Tag 格式 | `YYYYMMDD` / `YYYYMMDD-N` | `v<major>.<minor>.<patch>` |
| 验收 | 人能读懂 | 测试通过、能跑起来 |
| 分发渠道 | 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 "<project-name> V0.2.4"
git push <remote> v0.2.4
```
规则:
- 用 annotated tag(`-a`),不用 lightweight。
- Tag message 用英文,格式 `<Project Name> V<x.y.z>`,跟 displayVersion
一致。
- 一个版本一个 tag。同版本不同平台不要分多个 tag。
- 已经用于发行的 tag **不要移动**。错了发 patch(`v0.2.5`)覆盖。
- 误打的 tag 在**没用于发行前**可以删:
```bash
git tag -d v0.2.4
git push <remote> :refs/tags/v0.2.4
git tag -a v0.2.4 <correct-sha> -m "<Project> V0.2.4"
git push <remote> v0.2.4
```
## 分支策略
产品类项目至少有:
- **`dev`** —— 默认协作分支。日常开发、bug 修复、文档更新、发行前
准备都进这里。
- **功能分支** —— `<owner>/<slug>`,开 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/
```
进分发渠道(典型路径,按项目调):
```
/<project>/dist/ 面向使用者的发行 zip + manifest
/<project>/feedback/<machine-id>/ 用户上传的反馈
```
发行 zip **必须自包含**:用户解压点击就能跑,不在用户机器上装
依赖。具体内容随项目变,但原则不变。
## Manifest
每次发布在分发渠道根目录放一份 `manifest.json`,客户端启动时读它判
断有没有更新:
```json
{
"name": "<project-name>",
"version": "0.2.4",
"displayVersion": "V0.2.4",
"released_at": "2026-05-18T17:00:00Z",
"platforms": {
"windows": {
"url": "<dist-url>/<project>-v0.2.4-windows.zip",
"size": 123456789,
"sha256": "<hex>"
},
"macos-arm64": { "url": "...", "size": ..., "sha256": "..." },
"macos-x64": { "url": "...", "size": ..., "sha256": "..." }
},
"release_notes": "<short markdown>"
}
```
上传后**重新拉一遍** manifest,肉眼对一遍 size 和 sha256 是不是新的。
看到 size 跟旧版一致——分发渠道有缓存或上传出错。
## 更新机制
我们做的是"用户确认式更新",不是无人值守强推:
1. 客户端启动时拉 manifest,比版本号。
2. 有新版**提示用户**,不直接下载。
3. 用户点同意,下载到本地。
4. 用户点安装,重启生效。
任何一步不要替用户跳过。这条往后写进每个产品的 `CLAUDE.md` /
`AGENTS.md` 的"Don'ts"。
## 反馈与日志
反馈走"本地优先 + 异步上传":
```
本地:
feedback-records/feedback-<timestamp>-<id>.json
logs/<project>-YYYY-MM-DD.jsonl
云端(上传成功后):
/<project>/feedback/<machine-id>/<feedback-file>.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 <remote> dev
git status --short --branch
# 2. 检查
<lint command>
<test command>
# 3. 改版本号(按本项目的"必改清单"逐项改)
# package.json、UI 胶囊、server.js、build script、README
# 4. commit + tag
git add <files>
git commit -m "chore: release vX.Y.Z"
git tag -a vX.Y.Z HEAD -m "<Project> VX.Y.Z"
git push <remote> dev
git push <remote> vX.Y.Z
# 5. 构建
<build command>
# 6. 上传 manifest + zip 到分发渠道,验证 size/sha256
```
## 产品 README 必备段落
每个产品类项目的 README,在通用 README 模板基础上,**额外**包含:
- **版本状态段** —— 当前源码版本、内部版本号、协作分支、协作仓库、
历史迁移来源(如果有)、默认本地服务地址(如果有)、默认输出
目录。
- **快速启动段** —— 按平台分(Windows / macOS / Linux),覆盖
解压、启动、访问、关闭。
- **发行包内置内容清单** —— 让用户知道完整包应该有什么。
- **发版必改字段清单** —— 给开发者的,写明哪些文件要同步改版本号。
人填模板见 [`templates/README.md.template`](../templates/README.md.template);
产品项目按上面清单加段落。
## 最低交付标准(每次"可给别人用"的版本)
照搬 task_assistant 的清单,按项目改:
- [ ] `<remote>/dev` 有对应 commit
- [ ] `<remote>` 有对应 tag(`v<x.y.z>`)
- [ ] `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 够好就够用。
- 多环境配置体系 —— 真有需要再说。
+16
View File
@@ -0,0 +1,16 @@
{
"hooks": {
"SessionStart": [
{
"matcher": "startup|clear|compact",
"hooks": [
{
"type": "command",
"command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
"async": false
}
]
}
]
}
}
+47
View File
@@ -0,0 +1,47 @@
@echo off
REM Windows shim that invokes a bash hook script. Claude Code passes the
REM hook name as the first argument; we forward stdin and arguments to the
REM matching POSIX script under hooks/.
setlocal
REM Find git's bash. Required because Claude Code on Windows installations
REM does not always have a bash on PATH.
set "BASH_EXE="
for %%P in (
"%ProgramFiles%\Git\bin\bash.exe"
"%ProgramFiles(x86)%\Git\bin\bash.exe"
"%LocalAppData%\Programs\Git\bin\bash.exe"
) do (
if exist "%%~P" (
set "BASH_EXE=%%~P"
goto :found
)
)
REM Fallback: hope bash is on PATH.
where bash >nul 2>&1
if %ERRORLEVEL%==0 (
set "BASH_EXE=bash"
)
:found
if not defined BASH_EXE (
echo praxis hook: bash not found, skipping > nul
exit /b 0
)
set "HOOK_NAME=%~1"
if "%HOOK_NAME%"=="" (
echo praxis hook: no hook name provided 1>&2
exit /b 1
)
set "HOOK_SCRIPT=%~dp0%HOOK_NAME%"
if not exist "%HOOK_SCRIPT%" (
echo praxis hook: %HOOK_NAME% script not found 1>&2
exit /b 1
)
"%BASH_EXE%" "%HOOK_SCRIPT%"
exit /b %ERRORLEVEL%
+37
View File
@@ -0,0 +1,37 @@
#!/usr/bin/env bash
# SessionStart hook for praxis plugin.
# Loads using-praxis SKILL.md and injects it into the session context so the
# agent reads the iron-law / red-flags content before its first response.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
using_praxis_content=$(cat "${PLUGIN_ROOT}/skills/using-praxis/SKILL.md" 2>&1 || echo "Error reading using-praxis skill")
# Escape string for JSON embedding using bash parameter substitution.
escape_for_json() {
local s="$1"
s="${s//\\/\\\\}"
s="${s//\"/\\\"}"
s="${s//$'\n'/\\n}"
s="${s//$'\r'/\\r}"
s="${s//$'\t'/\\t}"
printf '%s' "$s"
}
using_praxis_escaped=$(escape_for_json "$using_praxis_content")
session_context="<EXTREMELY_IMPORTANT>\nYou are working in a Simgreek project that has the praxis plugin installed.\n\n**Below is the full content of your 'praxis:using-praxis' skill — your introduction to using praxis skills. For all other skills, use the 'Skill' tool:**\n\n${using_praxis_escaped}\n</EXTREMELY_IMPORTANT>"
# Output context injection. Claude Code expects hookSpecificOutput.additionalContext.
# Cursor expects additional_context (snake_case). Copilot CLI expects additionalContext top-level.
if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
printf '{\n "additional_context": "%s"\n}\n' "$session_context"
elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then
printf '{\n "hookSpecificOutput": {\n "hookEventName": "SessionStart",\n "additionalContext": "%s"\n }\n}\n' "$session_context"
else
printf '{\n "additionalContext": "%s"\n}\n' "$session_context"
fi
exit 0
+202
View File
@@ -0,0 +1,202 @@
---
name: debugging
description: Use when encountering any bug, test failure, or unexpected behavior, before proposing a fix — requires root-cause investigation before any code change
---
# Debugging — root cause before fix
## The Iron Law
```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
```
Random fixes waste time and create new bugs. Quick patches mask the
real problem and the same bug shows up later in a different form.
If you have not completed Phase 1 below, you cannot propose fixes.
## When to invoke this skill
Any technical issue:
- Test failures
- Bugs in dev or production
- Unexpected behavior
- Performance problems
- Build / typecheck failures
- Integration issues
**Especially when:**
- Time pressure (emergencies make guessing tempting)
- "Just one quick fix" looks obvious
- You've already tried multiple fixes
- Previous fix didn't work
- You don't fully understand what broke
**Don't skip when:**
- Issue seems simple — simple bugs have root causes too
- You're in a hurry — systematic is faster than thrashing
- The user wants it fixed NOW — guess-and-check makes it slower
## The four phases
You must complete each phase before proceeding to the next.
### Phase 1: Root cause investigation
Before attempting any fix:
1. **Read error messages carefully.** Don't skim past errors or
warnings. Read stack traces completely. Note line numbers, file
paths, error codes. The exact answer is often in the message.
2. **Reproduce consistently.** Can you trigger it reliably? What are
the exact steps? Every time? If not reproducible, gather more data
— don't guess.
3. **Check recent changes.** What changed that could cause this?
`git log --oneline -10`. New deps, config changes, environment
differences.
4. **Multi-component systems: gather evidence at boundaries.** When
the system has layers (CI → build → signing, API → service → DB),
add diagnostic logging at each layer before proposing fixes. Run
once to see WHERE it breaks, then investigate that specific layer.
Example layering:
```
For each component boundary:
- Log what data enters
- Log what data exits
- Verify env / config propagation
- Check state at each layer
Run once → identify failing layer → investigate that layer
```
5. **Trace data flow backward.** When the error is deep in the call
stack: where does the bad value originate? What called this with
the bad value? Keep tracing up until you find the source. Fix at
the source, not at the symptom.
### Phase 2: Pattern analysis
1. **Find a working example.** Locate similar code in the same
codebase that works. What does it do that the broken code doesn't?
2. **Compare against references.** If the broken code follows a
pattern (a library's example, a sister module), read the reference
completely. Don't skim. Understand it before applying it.
3. **Identify differences.** What's different between working and
broken? List every difference, however small. Don't assume "that
can't matter" — that assumption is usually how the bug got there.
4. **Understand dependencies.** What other components does this need?
What config / env / assumptions does it make?
### Phase 3: Hypothesis and minimal test
1. **Form a single hypothesis.** State it: "I think X is the root
cause because Y." Be specific. Vague hypothesis = vague fix.
2. **Test minimally.** Make the smallest possible change to test the
hypothesis. One variable at a time. Don't bundle multiple changes
"while you're in there."
3. **Verify before continuing.** Did it work? Yes → Phase 4. No →
form a NEW hypothesis. Don't pile fixes on top of fixes.
4. **When you don't know, say so.** "I don't understand why X happens"
is a valid status. Don't pretend. Ask, research, or surface to the
human.
### Phase 4: Fix and verify
1. **Write a failing test first.** Simplest possible reproduction.
Automated if the project has a framework; one-off script otherwise.
The test must fail with the current code — that's how you know it
actually targets the bug.
2. **Implement a single fix.** Address the root cause from Phase 1.
One change. No "while I'm here" cleanups, no bundled refactors.
3. **Verify.** Test passes? Other tests still pass? The original
reported symptom is gone?
4. **If the fix doesn't work:** stop. Count: how many fixes have you
tried?
- **<3**: return to Phase 1 with what you learned.
- **≥3**: stop and question the architecture (next step). Do **not**
try fix #4.
5. **3+ fixes failed = architectural problem, not a fix problem.**
Pattern indicators:
- Each fix reveals a new shared-state / coupling issue elsewhere.
- Fixes require "massive refactoring" to land cleanly.
- Each fix creates new symptoms in different places.
Surface to the human: "I've tried 3 approaches, each surfaces a
different downstream issue. I think the underlying pattern is wrong.
Want to discuss before I try more fixes?"
## Red Flags — STOP and follow the process
If you catch yourself thinking any of these, you are skipping the
process. Stop. Return to Phase 1.
| Thought | Reality |
|---------|---------|
| "Quick fix for now, investigate later" | "Later" never comes; the bug returns |
| "Just try changing X and see if it works" | That's guess-and-check, not debugging |
| "Add multiple changes, run tests" | Can't isolate what worked |
| "Skip the test, I'll manually verify" | Manual ≠ regression-proof |
| "It's probably X, let me fix that" | "Probably" is not a hypothesis |
| "Pattern says X but I'll adapt it" | Partial pattern = bug |
| "Here are the main problems: <list>" (without investigation) | Symptoms ≠ causes |
| Proposing fixes before tracing data flow | Always wrong |
| "One more fix attempt" (after 2+ failures) | Architectural problem |
| Each fix reveals new problem in different place | Architectural problem |
## Common rationalizations
| Excuse | Reality |
|--------|---------|
| "Issue is simple, no need for process" | Simple issues have root causes too. The process is fast for simple bugs. |
| "Emergency, no time for process" | Systematic debugging is **faster** than guess-and-check. |
| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
| "I'll write the test after confirming the fix" | Untested fixes don't stick. Test first proves the fix. |
| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
| "One more fix" (after 2+ failures) | Three failures = architectural problem. Don't fix again. |
## Quick reference
| Phase | Activity | Done when |
|-------|---------|-----------|
| 1. Root cause | Read errors, reproduce, check changes, trace data | You can describe WHAT and WHY |
| 2. Pattern | Find working example, compare, list differences | You know what to change |
| 3. Hypothesis | State theory, test minimally | Confirmed or new hypothesis |
| 4. Fix | Failing test → fix → verify | Original symptom is gone, no regressions |
## When the process reveals "no root cause"
If systematic investigation reveals the issue is genuinely
environmental, timing-dependent, or external:
1. You've completed the process — that's the answer.
2. Document what you investigated.
3. Implement appropriate handling: retry, timeout, clear error
message, monitoring.
But: 95% of "no root cause" diagnoses are incomplete investigation.
Be honest about which you're in.
## Related skills
- `verification` — verify the fix actually worked before claiming done
- `nodejs-project` — Phase 3 of nodejs SOP says "fail twice, invoke this skill"
+283
View File
@@ -0,0 +1,283 @@
---
name: git-upload
description: Use when pushing code to a remote, especially first push, adding a new file type the repo hasn't committed before, cleaning up .gitignore, or after suspecting a leaked secret
---
# git-upload — what to commit, what not to
This is a focused spec for what belongs in version control and what
doesn't. Branch / commit message / PR / tagging rules live in praxis
AGENTS.md §3.
## The first rule
`git status` and `git diff --cached` before every push. **Read every
file name in the staging list.** Most accidents happen because the
author didn't notice an extra file got staged.
## What goes in
Source and infrastructure for the project. Things that:
- Are written by humans (or AI under a human's review).
- Are reasonably small (text or small binaries — a few MB at most).
- Are the canonical version, not a derivative or cache.
Concretely:
- Source code, scripts, tests
- Configuration **templates** (e.g. `.env.example`) — never real values
- Schemas, fixtures, small reference datasets that are part of the project
- Documentation (Markdown, small images for docs)
- Lockfiles (`package-lock.json`, `poetry.lock`, `Cargo.lock`, etc.) —
always commit these
- Build / CI configuration
- License, README, CHANGELOG
## What stays out
### Secrets and credentials
**Never commit any of these, even once, even temporarily.**
- API keys, tokens, passwords (any provider)
- `.env`, `.env.local`, `.env.production`, `*.pem`, `*.key`, `id_rsa`,
`*.pfx`, `*.p12`
- OAuth client secrets, webhook signing keys
- Database connection strings with embedded passwords
- Cloud credentials (`~/.aws/credentials`, service account JSON)
- Personal access tokens in URLs (`https://user:TOKEN@host/repo.git`)
- Cookies, session tokens, signed JWTs from real users
A "delete the secret" commit later is **not enough** — the secret stays
in history. See [Recovering from a leaked secret](#recovering-from-a-leaked-secret).
### Generated and runtime files
These are derivatives — regenerable from sources, not source themselves.
```
# Build outputs
dist/ build/ out/ target/ .next/ .nuxt/
# Dependency caches
node_modules/ .venv/ venv/ __pycache__/ .pytest_cache/ .mypy_cache/
.tox/ .gradle/ vendor/ Pods/
# Editor / IDE state
.vscode/ .idea/ *.swp .DS_Store Thumbs.db desktop.ini
# Local runtime / logs
logs/ *.log tmp/ .cache/ runtime-temp/ feedback-records/
generated_*/ reports/
```
The exception: vendored dependencies that you **deliberately** want
under version control (offline / air-gapped builds). That's a project
decision documented in the project's AGENTS.md, not the default.
### Large binaries
> 5 MB → stop. Talk about Git LFS or out-of-band storage first.
Common offenders to scan for before pushing:
- Model weights (`.bin`, `.safetensors`, `.gguf`, `.ckpt`, `.pt`, `.onnx`)
- Datasets (`.parquet`, `.arrow`, `.zip`, `.tar.gz`, `.7z` over a few MB)
- Videos, raw images, audio
- Database dumps, full backups
- Vendor SDK installers
Once a large binary is in history, the repo is bloated forever (unless
you rewrite history). Catch it before push, not after.
### Personal / machine-specific files
- Personal editor settings — those go in `~/.<editor>` not the repo
- Agent personal config — `.claude/settings.local.json`,
`~/.codex/config.toml` (the personal one)
- Per-machine paths, hostnames, debug toggles
- Temporary scratch files, half-written notes
### User and customer data
- Real PII (names, emails, phone numbers from real people)
- Real internal records, customer logs, support tickets
- Anything covered by NDA or compliance scope
If sample data is needed for tests, generate it synthetically or use
public fixtures.
## .gitignore patterns
A baseline for most projects (adapt to the language):
```gitignore
# OS
.DS_Store
Thumbs.db
desktop.ini
# Editors
.vscode/
.idea/
*.swp
*~
# Secrets
.env
.env.*
!.env.example
*.pem
*.key
id_rsa*
*.pfx
*.p12
# Agent local state
.claude/settings.local.json
.claude/projects/
.claude/sessions/
# Python
__pycache__/
*.py[cod]
.venv/
venv/
.pytest_cache/
.mypy_cache/
# Node
node_modules/
npm-debug.log*
yarn-error.log
# Build outputs (uncomment what applies)
# dist/
# build/
# out/
# Logs / temp
*.log
tmp/
.cache/
```
Two rules for `.gitignore`:
1. **Be deliberate about negations** (`!.env.example` etc.) — they
override broader rules and are the source of "why isn't this file
ignored" confusion.
2. **`.gitignore` only ignores untracked files.** A file already in the
index keeps being tracked even if you add it to `.gitignore`. To
actually stop tracking it: `git rm --cached <file>` then commit.
## Staging discipline
`git add .` and `git add -A` are dangerous when there are unrecognized
untracked files. The safe pattern:
```bash
git status --short # see what's changed
git add <specific files> # stage by name
git diff --cached # read what's actually being committed
git commit -m "..."
```
If you have many related files and want to use a glob, prefer `git add
src/foo/` (a directory) over `git add .` (the world).
## Sensitive-info scan
Before push, especially when you've added new files:
```bash
git diff --cached
```
For periodic / pre-release scans across the working tree:
```bash
git grep -nE "sk-|hf_|Bearer |apiKey|ANTHROPIC_API_KEY|OPENAI_API_KEY|password|secret" \
-- ':!*.lock' ':!vendor/**' ':!**/__pycache__/**'
```
Hits need **human judgment** — demo keys in comments and real keys both
match the same regex. Don't blind-commit and don't blind-delete.
For a stronger sweep, use a dedicated tool (`gitleaks`, `trufflehog`,
or your platform's secret scanning). They have richer rule sets than
the regex above. Run them at least before any first-time push to a new
remote.
## Recovering from a leaked secret
When a real secret has been committed (and possibly pushed):
1. **Invalidate the secret immediately.** Rotate the key/token at the
provider before doing anything else. This is the only step that
actually makes the leak safe — everything below is cleanup.
2. Replace the secret locally. Move it to `.env` (which is gitignored)
or your secrets manager.
3. Notify collaborators. They need to know not to base work on the
compromised commit until history is rewritten.
4. Decide whether to rewrite history. For a public repo or one with a
short history, use `git filter-repo` (preferred over the deprecated
`filter-branch`) or your platform's secret-removal tooling. After
rewrite, force-push with team agreement and ask everyone to re-clone.
5. Document the incident briefly — what leaked, when, how, what was
done. Future-you will want this when a similar mistake happens.
A "delete the key" commit on top is **not safe**. The secret is still
in history and accessible to anyone who clones.
## URLs with embedded credentials
A common slip: pushing with a token-embedded URL writes the token into
`.git/config`:
```
remote "origin"
url = https://user:TOKEN@host/owner/repo.git
```
Fix: after pushing, reset the URL to the credential-free form and let
the credential helper handle auth:
```bash
git remote set-url origin https://host/owner/repo.git
```
Verify with `git remote -v`. The token also lives in shell history and
in any `.bash_history` / PowerShell history file — clear it if the
token is sensitive enough to warrant rotation.
## First push to a new remote
A short checklist when initializing a project:
- [ ] `.gitignore` covers secrets, build outputs, editor state, agent
local state
- [ ] No `.env` (or any `.env.*` other than `.env.example`) in the tree
- [ ] No files >5 MB in the tree
- [ ] `git status` shows only files you mean to commit
- [ ] `git diff --cached` reads cleanly — no surprise content
- [ ] Repo URL on the remote matches the one you intend; no token in
the URL
- [ ] Credential helper is configured (so you don't have to embed tokens
in URLs)
After first push: `git remote -v` should show a clean URL.
## Don'ts (summary)
- Don't `git add .` with unrecognized untracked files in the tree.
- Don't commit `.env`, secrets, tokens, or real credentials — ever, not
even temporarily.
- Don't commit large binaries (>5 MB) without a Git LFS conversation.
- Don't commit generated / cache directories.
- Don't commit real user data or PII.
- Don't try to "clean up" a leaked secret with a delete commit. Rotate
first, rewrite history if needed.
- Don't leave tokens in `.git/config` after a token-in-URL push.
- Don't `--no-verify` to skip pre-commit secret scans.
+233
View File
@@ -0,0 +1,233 @@
---
name: nodejs-project
description: Use in any project with a package.json — task execution SOP from project entry through release, including encoding/line-ending checks that prevent silent file corruption
---
# nodejs-project — AI execution SOP
This is the AI's task-execution sequence in any Node.js / Next.js
project. 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.
Invoke the `debugging` skill — that's what it's for.
## Phase 4 — Encoding & line-ending checks
Run before staging any text file changes. Source code 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.
`.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 (invoke `debugging`)
- 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
```
[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? invoke debugging.
[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.
```
+117
View File
@@ -0,0 +1,117 @@
---
name: using-praxis
description: Use when starting any conversation in a Simgreek project — establishes how to find and use praxis skills, requiring Skill tool invocation before ANY response including clarifying questions
---
<SUBAGENT-STOP>
If you were dispatched as a subagent to execute a specific task, skip this skill — your dispatcher already loaded praxis context.
</SUBAGENT-STOP>
<EXTREMELY-IMPORTANT>
If you think there is even a 1% chance a praxis skill might apply to what you are doing, you ABSOLUTELY MUST invoke it.
IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
This is not negotiable. This is not optional. You cannot rationalize your way out of this.
</EXTREMELY-IMPORTANT>
# Using Praxis
Praxis is the Simgreek team's coding agent rulebook — Greek for "practice." It exists because human teammates have been bitten by every shortcut you are about to take. The skills below encode those scars.
## Instruction Priority
Praxis skills override default agent behavior, but **the user's explicit instructions always take precedence**:
1. **User's explicit instructions** (project AGENTS.md, CLAUDE.md, direct chat) — highest
2. **Praxis skills** — override default behavior where they conflict
3. **Default agent behavior** — lowest
If a project's AGENTS.md says "skip the encoding check this once" and a skill says "always check encoding," follow the user. They own the project. You are a guest.
## How to Access Skills
**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its full content is loaded — follow it directly. Never use `Read` on a skill file when `Skill` is available.
**In Codex / Cursor / others:** Skills live as markdown files under `<plugin-root>/skills/`. Read the relevant ones with the file-reading tool.
# The Rule
**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means you must check. If an invoked skill turns out to be wrong for the situation, drop it — but you have to check first.
This includes:
- Before answering a clarifying question
- Before exploring the codebase
- Before "just running git status"
- Before reading docs to understand the project
- Before announcing what you're going to do
The skill check is the **first thing** that happens after you receive a message in a praxis-enabled project. Not the second. Not "after I look around real quick." First.
## Red Flags — These Thoughts Mean STOP
If you catch yourself thinking any of these, you are rationalizing past a skill. Stop, invoke the skill, then proceed.
| Thought | Reality |
|---------|---------|
| "This is just a simple question" | Questions are tasks. Check for skills. |
| "I need more context first" | Skill check comes BEFORE clarifying questions. |
| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
| "I can just check git status / read a file quickly" | Files lack conversation context. Check for skills. |
| "Let me gather information first" | Skills tell you HOW to gather information. |
| "This doesn't need a formal skill" | If a skill exists, use it. |
| "I remember this skill" | Skills evolve. Read the current version. |
| "This is a small change" | Small changes ship the bugs. Use the skill. |
| "The skill is overkill" | Simple things become complex when skipped. |
| "I'll just do this one thing first" | "One thing first" is how skills get bypassed. |
| "This feels productive" | Undisciplined motion wastes time. Skills prevent it. |
| "The user is in a hurry" | Skipping skills makes everything slower, not faster. |
| "I know what that means" | Knowing the concept ≠ following the procedure. Invoke. |
## The Praxis Skill Catalog
Read the catalog before your first action in this project. Match each candidate skill against the current task.
| Skill | When it applies |
|-------|-----------------|
| `git-upload` | Pushing to a remote, first push, adding new file types, leaked secret |
| `nodejs-project` | Any project with `package.json` — task execution SOP including encoding checks |
| `debugging` | Any bug, test failure, unexpected behavior, before proposing a fix |
| `verification` | About to claim work is complete, fixed, or passing |
If multiple apply, use them in order: process skills (`debugging`) before implementation skills (`nodejs-project`); verification (`verification`) before declaring done.
## Skill Priority
When multiple skills could apply:
1. **Process skills first** (`debugging`) — they determine HOW to approach the task
2. **Implementation skills second** (`nodejs-project`, `git-upload`) — they guide execution
3. **Verification last** (`verification`) — before declaring done
"Fix this bug" → `debugging` first, then `nodejs-project` if Node-relevant.
"Push my changes" → `git-upload` first, then `verification` before declaring done.
## Skill Types
**Rigid skills** (debugging, verification): follow exactly. The discipline is the value. Don't adapt away the steps you find inconvenient.
**Flexible skills** (nodejs-project SOP, git-upload pitfall list): adapt principles to context. The SOP is a default; deviate when the context demands and **state the deviation explicitly**.
The skill itself tells you which type it is.
## User Instructions
User instructions describe **what** to do, not **how**. "Add this feature" or "fix this bug" does not mean skip the workflow. The user sets the destination; praxis sets the route.
## What to Do Now
Before your next action:
1. Identify which skills in the catalog above might apply (1% threshold).
2. Invoke each one via the `Skill` tool (or read the file).
3. Follow its checklist.
4. Then proceed.
If the task is something praxis genuinely doesn't cover (e.g., "summarize this article"), proceed without a skill — but the check itself is mandatory.
+139
View File
@@ -0,0 +1,139 @@
---
name: verification
description: Use before claiming work is complete, fixed, or passing — requires running verification commands and reading output before making any success claim; evidence before assertions
---
# Verification — evidence before claims
## The Iron Law
```
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
```
Claiming work is complete without verification is dishonesty, not
efficiency. If you haven't run the verification command in this turn,
you cannot claim it passes.
## The gate
Before claiming any status or expressing satisfaction:
1. **Identify** the command that proves the claim.
2. **Run** it (fresh and complete — not a partial check, not a
remembered previous run).
3. **Read** the full output. Check the exit code. Count failures.
4. **Verify** the output confirms the claim.
- If yes: state the claim **with the evidence**.
- If no: state the actual status with the evidence.
5. **Only then** make the claim.
Skipping any step is lying, not verifying.
## Common claims and what proves them
| Claim | What proves it | What does NOT prove it |
|-------|----------------|------------------------|
| Tests pass | Test command output: 0 failures | "Should pass", a run from earlier |
| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
| Build succeeds | Build command exits 0 | Linter passing, logs look good |
| Bug fixed | Test the original symptom — passes | Code changed, "assumed fixed" |
| Regression test works | Red → green: test fails before fix, passes after | Test passes once after fix |
| Sub-agent completed | VCS diff shows the changes | Sub-agent reports "success" |
| Requirements met | Line-by-line checklist | "All tests pass" |
## Red Flags — STOP
If you catch yourself doing any of these, you're about to make an
unverified claim. Stop, run the verification, then continue.
- Using "should", "probably", "seems to", "I think"
- Saying "Great!", "Perfect!", "Done!" before running anything
- About to commit / push / open a PR without re-running checks in
this turn
- Trusting a sub-agent's success report without diff inspection
- Relying on partial verification (one file checked, claim covers
many)
- "Just this once"
- Tired and wanting the work over
- **Any wording implying success without evidence in this turn**
## Rationalizations
| Excuse | Reality |
|--------|---------|
| "Should work now" | RUN the verification |
| "I'm confident" | Confidence ≠ evidence |
| "Just this once" | No exceptions |
| "Linter passed" | Linter ≠ compiler ≠ tests |
| "Agent said success" | Verify independently |
| "I'm tired" | Exhaustion ≠ excuse |
| "Partial check is enough" | Partial proves nothing about the rest |
| "Different words, so the rule doesn't apply" | Spirit over letter |
## Patterns
**Tests:**
```
✅ Run `npm test` → output: "34 passing" → "All tests pass (34/34)."
❌ "Should pass now." / "Looks correct."
```
**Regression test (red-green):**
```
✅ Write test → run (pass) → revert fix → run (FAIL) → restore fix → run (pass)
❌ "I've added a regression test." (without red-green proof)
```
**Build:**
```
✅ Run `npm run build` → exit 0 → "Build passes."
❌ "Linter passed, build should be fine." (linter doesn't compile)
```
**Requirements:**
```
✅ Re-read the spec → check each line → report gaps or completion
❌ "Tests pass, so we're done." (tests ≠ requirements)
```
**Sub-agent delegation:**
```
✅ Sub-agent reports success → run `git diff` → confirm the changes
exist and are correct → report actual state
❌ Trust the sub-agent report
```
## When to apply
Always before:
- Any variation of "done", "complete", "fixed", "passing"
- Any expression of satisfaction about work state
- Committing, opening a PR, declaring task complete
- Moving to the next task in a multi-step plan
- Delegating verification to a sub-agent (verify their result yourself)
The rule applies to exact phrases, paraphrases, synonyms, and any
implication of success. "Spirit over letter."
## Why this matters
Unverified claims:
- Break the user's trust ("I don't believe you")
- Ship undefined functions or missing requirements
- Waste time on false completion → redirect → rework
Honesty is a core value. The cost of running the verification command
is small. The cost of being wrong is large.
## Bottom line
Run the command. Read the output. **Then** claim the result. Every
time.
-69
View File
@@ -1,69 +0,0 @@
# AGENTS.md — <project name>
<!--
Template. Copy into a new repo and fill the bracketed sections.
Sister file: CLAUDE.md (Claude Code reads that one). Keep them in sync.
Delete sections that don't apply. Keep total length under ~100 lines.
-->
## Project
<One or two sentences. What does it do, who is it for.>
## Run it
```bash
# install
<command>
# run
<command>
# test
<command>
# lint / typecheck
<command>
```
## Architecture
<One paragraph. Where are the entry points, how does data flow, what
are the major modules. Skip diagrams unless they save words.>
Key files:
- `<path>` — <one-line role>
- `<path>` — <one-line role>
## Conventions specific to this repo
<Anything that's not obvious from reading the code. Naming patterns,
where to add new features, what's auto-generated, etc.>
## Language policy
<If this project follows the team's bilingual policy, copy this:>
- Human-facing docs (README, `docs/*.md`, human-fillable templates) are
in Chinese.
- AI-facing files (`CLAUDE.md`, `AGENTS.md`, AI-only templates) are in
English.
- Commit messages, PR titles, branch names, tag annotations: English.
## Don'ts
<Things Codex / Claude / a new contributor has gotten wrong before.
One line each. Add to this list as you discover them.>
- Don't <…>
- Don't <…>
## External resources
<Links to dashboards, related repos, docs, ticket trackers.>
## Sync
When you edit this file, also update `CLAUDE.md` (and vice versa). The
two files describe the same project to different tools.
-69
View File
@@ -1,69 +0,0 @@
# CLAUDE.md — <project name>
<!--
Template. Copy into a new repo and fill the bracketed sections.
Sister file: AGENTS.md (Codex reads that one). Keep them in sync.
Delete sections that don't apply. Keep total length under ~100 lines.
-->
## Project
<One or two sentences. What does it do, who is it for.>
## Run it
```bash
# install
<command>
# run
<command>
# test
<command>
# lint / typecheck
<command>
```
## Architecture
<One paragraph. Where are the entry points, how does data flow, what
are the major modules. Skip diagrams unless they save words.>
Key files:
- `<path>` — <one-line role>
- `<path>` — <one-line role>
## Conventions specific to this repo
<Anything that's not obvious from reading the code. Naming patterns,
where to add new features, what's auto-generated, etc.>
## Language policy
<If this project follows the team's bilingual policy, copy this:>
- Human-facing docs (README, `docs/*.md`, human-fillable templates) are
in Chinese.
- AI-facing files (`CLAUDE.md`, `AGENTS.md`, AI-only templates) are in
English.
- Commit messages, PR titles, branch names, tag annotations: English.
## Don'ts
<Things Claude / Codex / a new contributor has gotten wrong before.
One line each. Add to this list as you discover them.>
- Don't <…>
- Don't <…>
## External resources
<Links to dashboards, related repos, docs, ticket trackers.>
## Sync
When you edit this file, also update `AGENTS.md` (and vice versa). The
two files describe the same project to different tools.
-65
View File
@@ -1,65 +0,0 @@
# Handoff 清单 — <包名或分支名>
<!--
交付前填完整。外部 handoff 一起放进包里;内部 handoff 放进 PR
description。正文中文,技术字段(commit hash、ISO 时间戳等)保留
英文格式。
-->
## 身份信息
- **名称**:<包名或分支名>
- **版本**:<比如 v0.5.0 或 commit sha 或 tag 比如 20260520>
- **生成时间**:<ISO 时间戳>
- **源仓库**:<url>
- **源 commit**:<full sha>
- **作者 / handoff owner**:<name>
- **接收方**:<name 或团队>
## 内容物
- [ ] `README.md` —— 这是什么、怎么用
- [ ] `CHANGELOG.md` —— 跟上一版的差异(首发就写"first release")
- [ ] `manifest.json` —— 机器可读元数据,所有字段都填了或显式 null
- [ ] `VERIFICATION.md` —— 检查了什么、结果如何
- [ ] 数据 / 产物 —— 真正的交付物
- [ ] 脚本 —— 仅限于使用本包必须的脚本
## 验证
- [ ] 记录数 / 文件数与预期一致
- [ ] Checksum 已计算并记录
- [ ] 合理性检查通过(列出来)
- [ ] 不含密钥、`.env`、credential
- [ ] 不含 PII(除非交付协议里就明确包含)
- [ ] 总大小在传输渠道可接受范围
验证报告路径:`<path>`
## 可重现性
- [ ] 已确认有源仓库访问的人能从 `source_commit` 重建产物(写明
谁测的、什么时候测的)
- [ ] 构建 / 生成命令写在 `README.md` 里
- [ ] 外部依赖锁版本
## 来源(AI 协助生成时填)
- 使用的模型:<比如 claude-opus-4-7、gpt-5-codex>
- 人工审核步骤:<人审 / 批准了哪些部分>
- 值得标注的 AI 决策:<半年后产物有问题时会想知道的事>
## 已知限制
<不能用的场景、未覆盖的边界、本版没赶上的后续。具体写。"在我机器
上能跑"不是限制——是发布前要修的问题。>
- <…>
- <…>
## 给接收方的说明
- [ ] 先读 `README.md`
- [ ] 跑验证报告 —— 不通过就停下来联系发送方
- [ ] <X 天>内确认收到
- [ ] 任何意外(缺文件、版本不对、命名异常)<X 天>内反馈给发送方
-49
View File
@@ -1,49 +0,0 @@
<!--
PR description 模板。标题写在 PR 标题栏,不在这里。
标题格式:<area>: <祈使句小结,70 字符以内>。英文。
正文中文。
-->
## Summary(小结)
<一句话说清这个 PR 干了什么。需要的话再加 1–3 条 bullet。>
- <bullet>
- <bullet>
## Why(为什么)
<动机。解决什么问题、落实什么决策、修哪个 bug。如果挂着 issue
或者之前的讨论,链上来。>
## What changed(改了什么)
<列出实际改动,跨多个区域时按区域分组。写事实就行——diff 是真相
来源,这只是地图。>
- `<文件或区域>` — <改动>
- `<文件或区域>` — <改动>
## Test plan(测试方案)
<勾选式 checklist。做了的勾 `[x]`,没做的留 `[ ]` 并在下面解释为什么。
诚实——"没测"可以接受,"声称测了但没测"不行。>
- [ ] 单元测试本地通过(`<command>`)
- [ ] Lint / typecheck 通过(`<command>`)
- [ ] <功能特定的检查>
- [ ] <功能特定的检查>
## Out of scope(范围外)
<你注意到但**显式选择不在这个 PR 修**的东西。帮 reviewer 不要在这些
点上提出来。>
## Notes for reviewer(给 reviewer 的提示)
<让你意外的地方、值得标注的 AI 协作决策、走过的捷径,或者"我考虑
过 X 但选了 Y 因为 Z"。没什么可写就删掉这一节。>
---
🤖 AI 协助完成(Claude Code / Codex)。
-62
View File
@@ -1,62 +0,0 @@
# <项目名>
<一句话。这是什么,用大白话写。>
## 这玩意儿干啥的
<一段话。比 tagline 多点细节。谁会用、解决什么问题、明确**不**做
什么。>
## 快速上手
```bash
# clone
git clone <url>
cd <repo>
# 安装
<command>
# 跑起来
<command>
```
预期输出:
```
<几行用户应该看到的内容>
```
## 开发
```bash
# 测试
<command>
# lint / typecheck
<command>
# 格式化
<command>
```
代码在 `<dir>`。测试在 `<dir>`。架构细节看 [docs/](docs/)(没有就
删掉这行)。
## 配置
<env var、配置文件、密钥。指向 `.env.example` 如果有的话。不写真实
值。>
## 数据来源 / 流向
<仅当不显然时写。输入从哪来,输出到哪去。>
## 相关链接
- <链接>
- <链接>
## License
<Internal / MIT / 等等。>