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>
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:
- Read this
AGENTS.md— general rules (vibe coding, Git, code style, planning, handoff). - Scan
skills/— narrower SOPs. Theusing-praxisskill lists the full catalog and tells you when to invoke each. - 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.mdonly. - AI-facing: English — this file,
CLAUDE.md, anything underskills/. - 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)
- Does the build / typecheck pass?
- Do tests pass — and do new tests actually exercise the new code?
- Are there files in the diff outside the stated scope? If yes, justify each or revert.
- Did this PR add dependencies? If yes, name them in the summary.
- Are there AI-generated comments restating what the code says? Delete.
- 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 --forcetomain/dev— ever. - No
--no-verifyto 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 -Awhen 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, notconfig.runTask, nottaskRunner. - Variables — what they are, not their type.
users, notuserArray.retryCount, notn. - Booleans —
is*,has*,should*.isReady, notready. - Constants —
UPPER_SNAKE_CASEonly at module level. Inside functions, plainconst. - No abbreviations unless they're domain terms.
database, notdb. (req/resin 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 counternext tocounter++// 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/exceptto 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:
- What is this? One paragraph.
- How do I run it? Bash blocks.
- How do I develop on it? Code layout, conventions.
- Where does data come from / go to? Only if non-obvious.
- 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 theSessionStarthook 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:
- 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 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:
-
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> -
Put the spec at the top of the PR description (draft PR is fine) before writing code.
-
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'sv1.0. - A package without a README. Even a one-line README beats none.
Receiving a handoff
- Read the README first, fully. Resist running scripts.
- Run the verification report. Fails → stop and message the sender before doing anything else.
- 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.
Readeverything 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.