Files
praxis/AGENTS.md
T
阿白叔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

24 KiB

AGENTS.md — praxis

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.

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.

Human-facing entry point: 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/ — narrower SOPs. The using-praxis skill 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. 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 (this repo)

  • One rule per bullet. If a rule needs a paragraph of justification, split the rule out and put the reason on a **Why:** line.
  • Lead with the rule, then **Why:**, then **How to apply:** only when the rule isn't self-evident.
  • No emoji.
  • 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 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 about to write Chinese into a file the human would never read (or English into a file only humans read), stop — wrong file.

CLAUDE.md and AGENTS.md sync

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.

For other projects in our workspace where the two files are physical copies (legacy or tool-mismatch reasons), the rules are:

  • 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.

When starting a new project, prefer the single-file approach: write AGENTS.md, make CLAUDE.md a one-line @AGENTS.md import.


1. Vibe coding — humans + AI work split

The premise

AI writes most of the code. Humans steer: framing problems, making decisions, deciding what's good enough. The point of AI assistance is to skip typing, not to skip thinking.

The split

AI does:

  • 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

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:

# 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> —

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

: <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:

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/. 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/ — bootstrap, iron-law / red-flags / catalog. Loaded automatically by the SessionStart hook when the praxis plugin is installed.
  • skills/git-upload/ — what to commit, what not to, how to recover from leaked secrets.
  • skills/nodejs-project/ — task execution SOP for Node.js / Next.js projects (8 phases, includes encoding checks).
  • skills/debugging/ — root-cause investigation before any fix; 4-phase process.
  • skills/verification/ — 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.

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 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:

{
  "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.

## 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.