Compare commits
9
Commits
20260520-2
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
eafd46a8ba | ||
|
|
4fa489691f | ||
|
|
ea1819f1d2 | ||
|
|
161559a83d | ||
|
|
17671b2b22 | ||
|
|
c8ce92a2ed | ||
|
|
c5e6ebb534 | ||
|
|
94eb7ef70a | ||
|
|
dfa84743f9 |
No files matched your search
@@ -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.2.0",
|
||||
"source": "./",
|
||||
"author": {
|
||||
"name": "Simgreek",
|
||||
"url": "https://git.simgreek.com/simgreek"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -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.2.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"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,38 @@
|
||||
{
|
||||
"name": "praxis",
|
||||
"version": "0.2.0",
|
||||
"description": "Simgreek team's AI coding agent rulebook: SOP for Node.js projects, git hygiene, debugging, verification.",
|
||||
"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"
|
||||
],
|
||||
"skills": "./skills/",
|
||||
"interface": {
|
||||
"displayName": "Praxis",
|
||||
"shortDescription": "Simgreek team's AI coding agent SOP",
|
||||
"longDescription": "Use Praxis to make AI coding agents follow Simgreek team conventions: project entry, task framing, git workflow, encoding checks, root-cause debugging, and verification before completion.",
|
||||
"developerName": "Simgreek",
|
||||
"category": "Coding",
|
||||
"capabilities": [
|
||||
"Interactive",
|
||||
"Read",
|
||||
"Write"
|
||||
],
|
||||
"defaultPrompt": [
|
||||
"I'm starting a new task in this project — what should I check first?",
|
||||
"Help me bootstrap this project to follow Praxis conventions."
|
||||
],
|
||||
"websiteURL": "https://git.simgreek.com/simgreek/praxis"
|
||||
}
|
||||
}
|
||||
@@ -1,91 +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` |
|
||||
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
|
||||
|
||||
- Tags follow `YYYYMMDD` (e.g. `20260520`). Multiple tags on the same
|
||||
day get a `-N` suffix (`20260520-2`).
|
||||
- Annotated tags only. Tag messages summarize what changed since the
|
||||
previous tag.
|
||||
- Tags are immutable once pushed. If a tag is wrong, cut a new one.
|
||||
- Tag only on `main`.
|
||||
### The premise
|
||||
|
||||
## Working directory expectations
|
||||
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 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.
|
||||
### 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:
|
||||
|
||||
```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,97 +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` |
|
||||
|
||||
## 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
|
||||
|
||||
- Tags follow `YYYYMMDD` (e.g. `20260520`). Multiple tags on the same
|
||||
day get a `-N` suffix (`20260520-2`).
|
||||
- Annotated tags only. Tag messages summarize what changed since the
|
||||
previous tag.
|
||||
- Tags are immutable once pushed. If a tag is wrong, cut a new one.
|
||||
- Tag only on `main`.
|
||||
|
||||
## 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
|
||||
@@ -1,74 +1,160 @@
|
||||
# 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)
|
||||
源自希腊语 *praxis*(实践)。Simgreek 团队的"踩过坑就写下来"的总和,给 AI agent 用。
|
||||
|
||||
每篇都很短。一条规则要超过半页才能解释清楚的,多半还不是规则——是个待讨论项。
|
||||
支持三种用法(按完整度排序):
|
||||
|
||||
- **作为 Claude Code 插件** —— `/plugin install praxis` 之后,session 一开 SessionStart hook 就把 `using-praxis` 强制注入 context,AI 行为受铁律约束。
|
||||
- **作为 Codex / Codex++ 插件** —— `/plugin add <praxis-url>` 装上,Codex 把 skills/ 里的 SKILL.md 注册成可调用的 skill。Codex 没有 SessionStart hook,但 skill 的 description 会让模型按需 invoke。
|
||||
- **作为外部规范**—— 不装插件也能用:AI 进项目前读 `AGENTS.md` + 扫 `skills/`,靠提示词显式调用。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。
|
||||
|
||||
升级:`/plugin update praxis`(自动用同一个 token 拉新版本)
|
||||
|
||||
卸载:`/plugin uninstall praxis`
|
||||
|
||||
## 安装(Codex / Codex++)
|
||||
|
||||
token 准备方式与 Claude Code 一致(上面第 1 步)。
|
||||
|
||||
**在 Codex CLI 或 Codex++ 里**:
|
||||
|
||||
```
|
||||
/plugin add https://<YOUR_USERNAME>:<YOUR_TOKEN>@git.simgreek.com/simgreek/praxis
|
||||
```
|
||||
|
||||
Codex 拉取仓库后会读 `.codex-plugin/plugin.json`,把 `skills/` 下所有带 frontmatter 的 SKILL.md 注册成可调用 skill。需要时 AI 自己 invoke。
|
||||
|
||||
**和 Claude 的差别**:Codex 没有 SessionStart hook,所以 `using-praxis` 不会被强制注入。AI 进项目时,建议你**第一句话**说:
|
||||
|
||||
```
|
||||
先读 using-praxis skill,了解我们团队的 SOP 再开始。
|
||||
```
|
||||
|
||||
让 Codex 主动 invoke 一次,铁律就在 context 里了。后续任务正常用。
|
||||
|
||||
**安全提醒(两边都适用)**:
|
||||
|
||||
- token 会被工具写进本地配置——别让别人翻你电脑、别把 config 分享出去
|
||||
- token 不要提交进任何仓库
|
||||
- 共用电脑 / 临时机器装完用完,去 Gitea token 页面 revoke 掉
|
||||
- token 失效或换了,重新跑 install 命令用新 URL
|
||||
|
||||
## 不装插件怎么用
|
||||
|
||||
把这段提示词丢给 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 同步规则
|
||||
└── 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,格式 `YYYYMMDD`,比如 `20260520`。
|
||||
本仓库按日期打 tag:`YYYYMMDD`(同一天多次发布加 `-N` 后缀)。tag 不可改、不可删、不可 force-push。
|
||||
|
||||
- `main` 永远是当前工作副本,随时合并。
|
||||
- 一天最多一个 tag。同一天有多次发布,用 `YYYYMMDD-N` 后缀(`20260520-2`)。
|
||||
- Tag 一旦推到远端就不能改、不能删、不能 force-push。
|
||||
- 大改写新 tag,不动旧 tag。
|
||||
- 谁要"用某一版",告诉对方 tag 名(例:`team-guide @ 20260520`)就行。
|
||||
具体规则见 [`AGENTS.md`](AGENTS.md) §3 Git workflow。项目仓库自己用各自的 tag 方案(通常 semver `vX.Y.Z`),写在项目的 `AGENTS.md` 里。
|
||||
|
||||
打 tag 的具体命令和场景见 [`docs/03-git-workflow.md`](docs/03-git-workflow.md) 的 Tag 一节。
|
||||
## Skill 怎么扩
|
||||
|
||||
最近 tag 列表:[git.simgreek.com/simgreek/team-guide/tags](https://git.simgreek.com/simgreek/team-guide/tags)
|
||||
碰到跨项目的具体话题、塞进 AGENTS.md 会拖肿(比如"PII 处理"、"eval 报告格式"),就在 `skills/<topic>/` 下写 `SKILL.md`。
|
||||
|
||||
收录标准(同时满足):
|
||||
|
||||
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
|
||||
|
||||
|
||||
@@ -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 想"既然来了顺便重构一下"——拒绝。开新任务。
|
||||
@@ -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 拉回来做新主题。陈旧上下文会
|
||||
渗进来。
|
||||
@@ -1,126 +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:`YYYYMMDD`(比如 `20260520`)。每个 tag 是 `main`
|
||||
某一时刻的快照——值得指着说"我们就按这版来"。
|
||||
|
||||
规则:
|
||||
|
||||
- 只在 `main` 上打 tag。功能分支打 tag 是 smell。
|
||||
- 一天最多一个 tag。同一天再切一个,加 `-N` 后缀:`20260520-2`、
|
||||
`20260520-3`。
|
||||
- 用 annotated tag,不用 lightweight。`git tag -a` 加一两句说自上次
|
||||
tag 以来改了什么。
|
||||
- Tag 一旦推到远端就不能改、不能删、不能 force-tag。错了就再切一个。
|
||||
- Tag commit、push tag、告诉大家 tag 名字——这就是发布。
|
||||
|
||||
切 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
|
||||
```
|
||||
|
||||
查看 / 对比:
|
||||
|
||||
```bash
|
||||
git tag --sort=-creatordate # 按时间倒序
|
||||
git show 20260520 # 看一个 tag 里有什么
|
||||
git log --oneline 20260513..20260520 # 两个 tag 之间改了什么
|
||||
```
|
||||
|
||||
什么时候切 tag:
|
||||
|
||||
- 本仓库的 docs 改了,队友需要重新读。
|
||||
- 加了、删了或重组了 template。
|
||||
- 新的约定正式生效(不是还在讨论)。
|
||||
|
||||
什么时候**不**切 tag:
|
||||
|
||||
- 改错别字、调格式、修死链 → 直接 push 到 `main`。
|
||||
- 还在讨论的草稿 → 走 PR,不打 tag。
|
||||
|
||||
## 不要做的事
|
||||
|
||||
- 不要 `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`。
|
||||
按文件名加。
|
||||
@@ -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 说明在做错的东西。
|
||||
- 不是状态秀。周一帖是为了发现卡点,不是证明你干了活。
|
||||
@@ -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。
|
||||
- 不要没量就先优化。"可能慢"不是测量结果。
|
||||
@@ -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 用。
|
||||
@@ -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`。
|
||||
@@ -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
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -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%
|
||||
Executable
+37
@@ -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
|
||||
@@ -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"
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
```
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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 天>内反馈给发送方
|
||||
@@ -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)。
|
||||
@@ -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 / 等等。>
|
||||
Reference in new issue
Block a user