5 Commits
Author SHA1 Message Date
阿白叔andClaude Opus 4.7 ea1819f1d2 feat: rename to praxis, package as Claude Code plugin
Reframe team-guide as praxis (Greek for "practice"): Simgreek's coding
agent rulebook, distributed as a Claude Code plugin so SessionStart
hook can force-inject the using-praxis bootstrap.

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

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

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

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

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

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

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

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

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

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

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

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 23:38:46 +08:00
17 changed files with 1528 additions and 906 deletions

No files matched your search

+20
View File
@@ -0,0 +1,20 @@
{
"name": "praxis",
"description": "Simgreek team's coding agent SOP marketplace.",
"owner": {
"name": "Simgreek",
"url": "https://git.simgreek.com/simgreek"
},
"plugins": [
{
"name": "praxis",
"description": "Simgreek team's AI coding agent rulebook: SOP for Node.js projects, git hygiene, debugging, verification.",
"version": "0.1.0",
"source": "./",
"author": {
"name": "Simgreek",
"url": "https://git.simgreek.com/simgreek"
}
}
]
}
+20
View File
@@ -0,0 +1,20 @@
{
"name": "praxis",
"description": "Simgreek team's AI coding agent rulebook: SOP for Node.js projects, git hygiene, debugging, verification — practice over theory.",
"version": "0.1.0",
"author": {
"name": "Simgreek",
"url": "https://git.simgreek.com/simgreek"
},
"homepage": "https://git.simgreek.com/simgreek/praxis",
"repository": "https://git.simgreek.com/simgreek/praxis",
"license": "Internal",
"keywords": [
"skills",
"sop",
"nodejs",
"git",
"debugging",
"team-rules"
]
}
+323 -548
View File
File diff suppressed because it is too large. Load diff
+91 -44
View File
@@ -1,71 +1,118 @@
# team-guide
# praxis
我们小团队的 AI 协作(vibe coding)开发约定。1–3 人规模,规则不多但都是真踩过的坑。
Simgreek 团队的 AI 协作开发约定。**给 AI 看的**——每个项目里 AI 开干前先读这里。
完整规则在 [`AGENTS.md`](AGENTS.md)(英文,给 AI 看)——本仓库的**唯一规则来源**。
这份 README 是给人的导览,知道去哪查、怎么参与就行。
完整规则在 [`AGENTS.md`](AGENTS.md)(英文)。skill 库在 [`skills/`](skills/)。这份 README 是给人的入口说明。
## 怎么用
## praxis 是什么
1. **新成员** —— 读这份 README 五分钟,再扫一眼 [AGENTS.md](AGENTS.md) 的目录。具体规则用到再翻。
2. **新项目** —— 从 [`templates/`](templates/) 复制对应模板。新仓库根目录放 `AGENTS.md`,再放一行 `@AGENTS.md` 的 `CLAUDE.md`,让 Claude Code 和 Codex 读同一份。
3. **不同意某条规则** —— 在本仓库开 PR 改它,不要私下绕开。
源自希腊语 *praxis*(实践)。Simgreek 团队的"踩过坑就写下来"的总和,给 AI agent 用。
两种用法:
- **作为 Claude Code 插件**(推荐)—— `/plugin install praxis` 之后,session 一开 hook 就把 `using-praxis` 强制注入 context,AI 行为受铁律约束。
- **作为外部规范**—— 不装插件也能用:AI 进项目前读 `AGENTS.md` + 扫 `skills/`,靠自觉调用。Codex / Cursor 走这条。
## 安装(Claude Code 插件)
```
/plugin marketplace add https://git.simgreek.com/simgreek/praxis
/plugin install praxis
```
装完之后每次开新 session,praxis 的 `SessionStart` hook 会把 `using-praxis` 内容直接灌进 system context——AI 在做任何事之前都会读到铁律和 red flags。
升级:`/plugin update praxis`
卸载:`/plugin uninstall praxis`
## 不装插件怎么用
把这段提示词丢给 AI 当首句话:
```text
请按以下顺序为本项目做初始化或推进任务:
1. 拉取并阅读 https://git.simgreek.com/simgreek/praxis 的最新内容
(至少读 AGENTS.md 和 skills/using-praxis/SKILL.md,再扫 skills/
下的其他 SKILL.md,匹配当前任务的读完)。
2. 读完后,如果是新项目初始化,问我以下信息(一次性问完):
- 项目名 / 一句话定位
- 技术栈(Node 版本、是否 Next.js / Express / 其他)
- 远端仓库地址(gitee / git.simgreek.com / 其他)
- 协作主分支名(main / dev)
- 是否产品项目(要发分发渠道);是的话,分发渠道是什么
- 需要哪些环境变量(只要变量名,不要值)
3. 拿到回答后,按 praxis 的规范:
- git init(如果还没)+ 配 .gitignore(含 node_modules / .env*
/ 构建产物 / .claude/settings.local.json 等)
- 落 .gitattributes(强制 LF,.bat/.cmd 用 CRLF,二进制标 binary)
- 写 .env.example(仅变量名)
- 写项目根 AGENTS.md,遵循 praxis AGENTS.md §2 的骨架,引用 praxis
而不是复制规则
- CLAUDE.md 写一行:@AGENTS.md
- 写 README.md(中文,给人看,三段:是什么 / 怎么跑 / 怎么配 .env)
4. 全部建好后列出改动,等我确认再 commit。第一个 commit 不直接 push。
5. 整个过程严格遵守 praxis 的「AI 必须停下问人」规则——任务模糊、
范围敏感、远端冲突、--force、上传分发渠道,这些必须停下来确认。
```
老项目补规范,把第 3 步换成"补齐缺失的文件,不要覆盖现有的内容;冲突先列出来问我"。
## 语言策略
- **给人看的(中文)**:本 README、`templates/` 里给人填的(README、PR、handoff)。
- **给 AI 看的(英文)**:[`AGENTS.md`](AGENTS.md)、[`CLAUDE.md`](CLAUDE.md)、AI 专用模板。
- **Git 元数据(英文)**:commit、PR 标题、分支名、tag 注释。
理由:AI 工具和搜索更吃英文 metadata;规则只需要一份不需要两份;中文给人在入口处看到。
- **本 README 中文**——给人读的入口
- **AGENTS.md / CLAUDE.md / skills/ 全英文**——给 AI 读
- **commit、PR 标题、分支名、tag 注释全英文**——AI 工具和搜索吃英文 metadata 更准
## 目录
```
team-guide/
├── README.md ← 你正在看(中文,给人)
├── AGENTS.md ← 全部规则(英文,给 AI)
├── CLAUDE.md ← 一行 @AGENTS.md import
└── templates/ ← 新项目脚手架
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/ ← 完成前必须有证据
```
[`AGENTS.md`](AGENTS.md) 内含 7 大章:
项目背景与编辑规则 · Vibe coding · Claude Code & Codex 配置 ·
Git 工作流 · 代码与产出风格 · 产品类项目(semver、manifest、发版)·
规划节奏 · Handoff。
## 版本管理
按**项目类型**分两种 tag 风格:
本仓库按日期打 tag:`YYYYMMDD`(同一天多次发布加 `-N` 后缀)。tag 不可改、不可删、不可 force-push。
- **规范类**(本仓库 team-guide、其他规约文档)—— 按日期 `YYYYMMDD`,比如 `20260520`。同一天多次发布加 `-N` 后缀(`20260520-2`)。从 `main` 打 tag。
- **产品类**(task_assistant、authoring-tool 这种有版本、有发行包的)—— semver `vX.Y.Z`,比如 `v0.2.4`。三处版本号必须同步:内部 `0.2.4` / 显示 `V0.2.4` / tag `v0.2.4`。从 `dev` 打 tag。
具体规则见 [`AGENTS.md`](AGENTS.md) §3 Git workflow。项目仓库自己用各自的 tag 方案(通常 semver `vX.Y.Z`),写在项目的 `AGENTS.md` 里。
通用规则:
## Skill 怎么扩
- `main`(规范类)/ `dev`(产品类)永远是当前工作副本。
- 只用 annotated tag(`git tag -a`)。
- Tag 一旦推到远端就不能改、不能删、不能 force-push。错了切新的。
- 谁要"用某一版",告诉对方 tag 名(`team-guide @ 20260520`、`task_assistant @ v0.2.4`)就行。
碰到跨项目的具体话题、塞进 AGENTS.md 会拖肿(比如"PII 处理"、"eval 报告格式"),就在 `skills/<topic>/` 下写 `SKILL.md`。
具体命令、什么时候切 tag、产品项目发版细则——见 [`AGENTS.md`](AGENTS.md) 的 Git workflow 和 Product projects 两节。
收录标准(同时满足):
## 几条最容易踩的线(速查)
1. 至少踩过两次
2. 比 AGENTS.md 通用规则窄
3. 步骤稳定到能写下来
完整版在 AGENTS.md,这里挑人最常忘的:
- 长 session 的上下文会污染输出,新任务开新 session
- 不读 diff 就 "looks good" 是 bug 上线的标准姿势
- 一个 session 不要同时让 Claude Code 和 Codex 改同一个文件
- AI 试同一个方案两次报同样的错——叫停,自己上
- 改了 `CLAUDE.md` / `AGENTS.md` 一边,另一边要在同一个 PR 里同步(本仓库已经用 `@AGENTS.md` 解决了,新项目要注意)
- 提交前 `git diff --cached` 扫一眼,密钥误提交的应急流程在 AGENTS.md 的 Sensitive-info scan 节
- 产品发版"必改字段清单"漏一处下版就漂移——清单写进项目自己的 AGENTS.md
新加的 skill 要同时更新 AGENTS.md §5 Skills catalog 和 `using-praxis/SKILL.md` 的目录表。
## 远端
[git.simgreek.com/simgreek/team-guide](https://git.simgreek.com/simgreek/team-guide) ·
[tags 列表](https://git.simgreek.com/simgreek/team-guide/tags)
[git.simgreek.com/simgreek/praxis](https://git.simgreek.com/simgreek/praxis) ·
[tags 列表](https://git.simgreek.com/simgreek/praxis/tags)
## License
+16
View File
@@ -0,0 +1,16 @@
{
"hooks": {
"SessionStart": [
{
"matcher": "startup|clear|compact",
"hooks": [
{
"type": "command",
"command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
"async": false
}
]
}
]
}
}
+47
View File
@@ -0,0 +1,47 @@
@echo off
REM Windows shim that invokes a bash hook script. Claude Code passes the
REM hook name as the first argument; we forward stdin and arguments to the
REM matching POSIX script under hooks/.
setlocal
REM Find git's bash. Required because Claude Code on Windows installations
REM does not always have a bash on PATH.
set "BASH_EXE="
for %%P in (
"%ProgramFiles%\Git\bin\bash.exe"
"%ProgramFiles(x86)%\Git\bin\bash.exe"
"%LocalAppData%\Programs\Git\bin\bash.exe"
) do (
if exist "%%~P" (
set "BASH_EXE=%%~P"
goto :found
)
)
REM Fallback: hope bash is on PATH.
where bash >nul 2>&1
if %ERRORLEVEL%==0 (
set "BASH_EXE=bash"
)
:found
if not defined BASH_EXE (
echo praxis hook: bash not found, skipping > nul
exit /b 0
)
set "HOOK_NAME=%~1"
if "%HOOK_NAME%"=="" (
echo praxis hook: no hook name provided 1>&2
exit /b 1
)
set "HOOK_SCRIPT=%~dp0%HOOK_NAME%"
if not exist "%HOOK_SCRIPT%" (
echo praxis hook: %HOOK_NAME% script not found 1>&2
exit /b 1
)
"%BASH_EXE%" "%HOOK_SCRIPT%"
exit /b %ERRORLEVEL%
+37
View File
@@ -0,0 +1,37 @@
#!/usr/bin/env bash
# SessionStart hook for praxis plugin.
# Loads using-praxis SKILL.md and injects it into the session context so the
# agent reads the iron-law / red-flags content before its first response.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
using_praxis_content=$(cat "${PLUGIN_ROOT}/skills/using-praxis/SKILL.md" 2>&1 || echo "Error reading using-praxis skill")
# Escape string for JSON embedding using bash parameter substitution.
escape_for_json() {
local s="$1"
s="${s//\\/\\\\}"
s="${s//\"/\\\"}"
s="${s//$'\n'/\\n}"
s="${s//$'\r'/\\r}"
s="${s//$'\t'/\\t}"
printf '%s' "$s"
}
using_praxis_escaped=$(escape_for_json "$using_praxis_content")
session_context="<EXTREMELY_IMPORTANT>\nYou are working in a Simgreek project that has the praxis plugin installed.\n\n**Below is the full content of your 'praxis:using-praxis' skill — your introduction to using praxis skills. For all other skills, use the 'Skill' tool:**\n\n${using_praxis_escaped}\n</EXTREMELY_IMPORTANT>"
# Output context injection. Claude Code expects hookSpecificOutput.additionalContext.
# Cursor expects additional_context (snake_case). Copilot CLI expects additionalContext top-level.
if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
printf '{\n "additional_context": "%s"\n}\n' "$session_context"
elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then
printf '{\n "hookSpecificOutput": {\n "hookEventName": "SessionStart",\n "additionalContext": "%s"\n }\n}\n' "$session_context"
else
printf '{\n "additionalContext": "%s"\n}\n' "$session_context"
fi
exit 0
+202
View File
@@ -0,0 +1,202 @@
---
name: debugging
description: Use when encountering any bug, test failure, or unexpected behavior, before proposing a fix — requires root-cause investigation before any code change
---
# Debugging — root cause before fix
## The Iron Law
```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
```
Random fixes waste time and create new bugs. Quick patches mask the
real problem and the same bug shows up later in a different form.
If you have not completed Phase 1 below, you cannot propose fixes.
## When to invoke this skill
Any technical issue:
- Test failures
- Bugs in dev or production
- Unexpected behavior
- Performance problems
- Build / typecheck failures
- Integration issues
**Especially when:**
- Time pressure (emergencies make guessing tempting)
- "Just one quick fix" looks obvious
- You've already tried multiple fixes
- Previous fix didn't work
- You don't fully understand what broke
**Don't skip when:**
- Issue seems simple — simple bugs have root causes too
- You're in a hurry — systematic is faster than thrashing
- The user wants it fixed NOW — guess-and-check makes it slower
## The four phases
You must complete each phase before proceeding to the next.
### Phase 1: Root cause investigation
Before attempting any fix:
1. **Read error messages carefully.** Don't skim past errors or
warnings. Read stack traces completely. Note line numbers, file
paths, error codes. The exact answer is often in the message.
2. **Reproduce consistently.** Can you trigger it reliably? What are
the exact steps? Every time? If not reproducible, gather more data
— don't guess.
3. **Check recent changes.** What changed that could cause this?
`git log --oneline -10`. New deps, config changes, environment
differences.
4. **Multi-component systems: gather evidence at boundaries.** When
the system has layers (CI → build → signing, API → service → DB),
add diagnostic logging at each layer before proposing fixes. Run
once to see WHERE it breaks, then investigate that specific layer.
Example layering:
```
For each component boundary:
- Log what data enters
- Log what data exits
- Verify env / config propagation
- Check state at each layer
Run once → identify failing layer → investigate that layer
```
5. **Trace data flow backward.** When the error is deep in the call
stack: where does the bad value originate? What called this with
the bad value? Keep tracing up until you find the source. Fix at
the source, not at the symptom.
### Phase 2: Pattern analysis
1. **Find a working example.** Locate similar code in the same
codebase that works. What does it do that the broken code doesn't?
2. **Compare against references.** If the broken code follows a
pattern (a library's example, a sister module), read the reference
completely. Don't skim. Understand it before applying it.
3. **Identify differences.** What's different between working and
broken? List every difference, however small. Don't assume "that
can't matter" — that assumption is usually how the bug got there.
4. **Understand dependencies.** What other components does this need?
What config / env / assumptions does it make?
### Phase 3: Hypothesis and minimal test
1. **Form a single hypothesis.** State it: "I think X is the root
cause because Y." Be specific. Vague hypothesis = vague fix.
2. **Test minimally.** Make the smallest possible change to test the
hypothesis. One variable at a time. Don't bundle multiple changes
"while you're in there."
3. **Verify before continuing.** Did it work? Yes → Phase 4. No →
form a NEW hypothesis. Don't pile fixes on top of fixes.
4. **When you don't know, say so.** "I don't understand why X happens"
is a valid status. Don't pretend. Ask, research, or surface to the
human.
### Phase 4: Fix and verify
1. **Write a failing test first.** Simplest possible reproduction.
Automated if the project has a framework; one-off script otherwise.
The test must fail with the current code — that's how you know it
actually targets the bug.
2. **Implement a single fix.** Address the root cause from Phase 1.
One change. No "while I'm here" cleanups, no bundled refactors.
3. **Verify.** Test passes? Other tests still pass? The original
reported symptom is gone?
4. **If the fix doesn't work:** stop. Count: how many fixes have you
tried?
- **<3**: return to Phase 1 with what you learned.
- **≥3**: stop and question the architecture (next step). Do **not**
try fix #4.
5. **3+ fixes failed = architectural problem, not a fix problem.**
Pattern indicators:
- Each fix reveals a new shared-state / coupling issue elsewhere.
- Fixes require "massive refactoring" to land cleanly.
- Each fix creates new symptoms in different places.
Surface to the human: "I've tried 3 approaches, each surfaces a
different downstream issue. I think the underlying pattern is wrong.
Want to discuss before I try more fixes?"
## Red Flags — STOP and follow the process
If you catch yourself thinking any of these, you are skipping the
process. Stop. Return to Phase 1.
| Thought | Reality |
|---------|---------|
| "Quick fix for now, investigate later" | "Later" never comes; the bug returns |
| "Just try changing X and see if it works" | That's guess-and-check, not debugging |
| "Add multiple changes, run tests" | Can't isolate what worked |
| "Skip the test, I'll manually verify" | Manual ≠ regression-proof |
| "It's probably X, let me fix that" | "Probably" is not a hypothesis |
| "Pattern says X but I'll adapt it" | Partial pattern = bug |
| "Here are the main problems: <list>" (without investigation) | Symptoms ≠ causes |
| Proposing fixes before tracing data flow | Always wrong |
| "One more fix attempt" (after 2+ failures) | Architectural problem |
| Each fix reveals new problem in different place | Architectural problem |
## Common rationalizations
| Excuse | Reality |
|--------|---------|
| "Issue is simple, no need for process" | Simple issues have root causes too. The process is fast for simple bugs. |
| "Emergency, no time for process" | Systematic debugging is **faster** than guess-and-check. |
| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
| "I'll write the test after confirming the fix" | Untested fixes don't stick. Test first proves the fix. |
| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
| "One more fix" (after 2+ failures) | Three failures = architectural problem. Don't fix again. |
## Quick reference
| Phase | Activity | Done when |
|-------|---------|-----------|
| 1. Root cause | Read errors, reproduce, check changes, trace data | You can describe WHAT and WHY |
| 2. Pattern | Find working example, compare, list differences | You know what to change |
| 3. Hypothesis | State theory, test minimally | Confirmed or new hypothesis |
| 4. Fix | Failing test → fix → verify | Original symptom is gone, no regressions |
## When the process reveals "no root cause"
If systematic investigation reveals the issue is genuinely
environmental, timing-dependent, or external:
1. You've completed the process — that's the answer.
2. Document what you investigated.
3. Implement appropriate handling: retry, timeout, clear error
message, monitoring.
But: 95% of "no root cause" diagnoses are incomplete investigation.
Be honest about which you're in.
## Related skills
- `verification` — verify the fix actually worked before claiming done
- `nodejs-project` — Phase 3 of nodejs SOP says "fail twice, invoke this skill"
+283
View File
@@ -0,0 +1,283 @@
---
name: git-upload
description: Use when pushing code to a remote, especially first push, adding a new file type the repo hasn't committed before, cleaning up .gitignore, or after suspecting a leaked secret
---
# git-upload — what to commit, what not to
This is a focused spec for what belongs in version control and what
doesn't. Branch / commit message / PR / tagging rules live in praxis
AGENTS.md §3.
## The first rule
`git status` and `git diff --cached` before every push. **Read every
file name in the staging list.** Most accidents happen because the
author didn't notice an extra file got staged.
## What goes in
Source and infrastructure for the project. Things that:
- Are written by humans (or AI under a human's review).
- Are reasonably small (text or small binaries — a few MB at most).
- Are the canonical version, not a derivative or cache.
Concretely:
- Source code, scripts, tests
- Configuration **templates** (e.g. `.env.example`) — never real values
- Schemas, fixtures, small reference datasets that are part of the project
- Documentation (Markdown, small images for docs)
- Lockfiles (`package-lock.json`, `poetry.lock`, `Cargo.lock`, etc.) —
always commit these
- Build / CI configuration
- License, README, CHANGELOG
## What stays out
### Secrets and credentials
**Never commit any of these, even once, even temporarily.**
- API keys, tokens, passwords (any provider)
- `.env`, `.env.local`, `.env.production`, `*.pem`, `*.key`, `id_rsa`,
`*.pfx`, `*.p12`
- OAuth client secrets, webhook signing keys
- Database connection strings with embedded passwords
- Cloud credentials (`~/.aws/credentials`, service account JSON)
- Personal access tokens in URLs (`https://user:TOKEN@host/repo.git`)
- Cookies, session tokens, signed JWTs from real users
A "delete the secret" commit later is **not enough** — the secret stays
in history. See [Recovering from a leaked secret](#recovering-from-a-leaked-secret).
### Generated and runtime files
These are derivatives — regenerable from sources, not source themselves.
```
# Build outputs
dist/ build/ out/ target/ .next/ .nuxt/
# Dependency caches
node_modules/ .venv/ venv/ __pycache__/ .pytest_cache/ .mypy_cache/
.tox/ .gradle/ vendor/ Pods/
# Editor / IDE state
.vscode/ .idea/ *.swp .DS_Store Thumbs.db desktop.ini
# Local runtime / logs
logs/ *.log tmp/ .cache/ runtime-temp/ feedback-records/
generated_*/ reports/
```
The exception: vendored dependencies that you **deliberately** want
under version control (offline / air-gapped builds). That's a project
decision documented in the project's AGENTS.md, not the default.
### Large binaries
> 5 MB → stop. Talk about Git LFS or out-of-band storage first.
Common offenders to scan for before pushing:
- Model weights (`.bin`, `.safetensors`, `.gguf`, `.ckpt`, `.pt`, `.onnx`)
- Datasets (`.parquet`, `.arrow`, `.zip`, `.tar.gz`, `.7z` over a few MB)
- Videos, raw images, audio
- Database dumps, full backups
- Vendor SDK installers
Once a large binary is in history, the repo is bloated forever (unless
you rewrite history). Catch it before push, not after.
### Personal / machine-specific files
- Personal editor settings — those go in `~/.<editor>` not the repo
- Agent personal config — `.claude/settings.local.json`,
`~/.codex/config.toml` (the personal one)
- Per-machine paths, hostnames, debug toggles
- Temporary scratch files, half-written notes
### User and customer data
- Real PII (names, emails, phone numbers from real people)
- Real internal records, customer logs, support tickets
- Anything covered by NDA or compliance scope
If sample data is needed for tests, generate it synthetically or use
public fixtures.
## .gitignore patterns
A baseline for most projects (adapt to the language):
```gitignore
# OS
.DS_Store
Thumbs.db
desktop.ini
# Editors
.vscode/
.idea/
*.swp
*~
# Secrets
.env
.env.*
!.env.example
*.pem
*.key
id_rsa*
*.pfx
*.p12
# Agent local state
.claude/settings.local.json
.claude/projects/
.claude/sessions/
# Python
__pycache__/
*.py[cod]
.venv/
venv/
.pytest_cache/
.mypy_cache/
# Node
node_modules/
npm-debug.log*
yarn-error.log
# Build outputs (uncomment what applies)
# dist/
# build/
# out/
# Logs / temp
*.log
tmp/
.cache/
```
Two rules for `.gitignore`:
1. **Be deliberate about negations** (`!.env.example` etc.) — they
override broader rules and are the source of "why isn't this file
ignored" confusion.
2. **`.gitignore` only ignores untracked files.** A file already in the
index keeps being tracked even if you add it to `.gitignore`. To
actually stop tracking it: `git rm --cached <file>` then commit.
## Staging discipline
`git add .` and `git add -A` are dangerous when there are unrecognized
untracked files. The safe pattern:
```bash
git status --short # see what's changed
git add <specific files> # stage by name
git diff --cached # read what's actually being committed
git commit -m "..."
```
If you have many related files and want to use a glob, prefer `git add
src/foo/` (a directory) over `git add .` (the world).
## Sensitive-info scan
Before push, especially when you've added new files:
```bash
git diff --cached
```
For periodic / pre-release scans across the working tree:
```bash
git grep -nE "sk-|hf_|Bearer |apiKey|ANTHROPIC_API_KEY|OPENAI_API_KEY|password|secret" \
-- ':!*.lock' ':!vendor/**' ':!**/__pycache__/**'
```
Hits need **human judgment** — demo keys in comments and real keys both
match the same regex. Don't blind-commit and don't blind-delete.
For a stronger sweep, use a dedicated tool (`gitleaks`, `trufflehog`,
or your platform's secret scanning). They have richer rule sets than
the regex above. Run them at least before any first-time push to a new
remote.
## Recovering from a leaked secret
When a real secret has been committed (and possibly pushed):
1. **Invalidate the secret immediately.** Rotate the key/token at the
provider before doing anything else. This is the only step that
actually makes the leak safe — everything below is cleanup.
2. Replace the secret locally. Move it to `.env` (which is gitignored)
or your secrets manager.
3. Notify collaborators. They need to know not to base work on the
compromised commit until history is rewritten.
4. Decide whether to rewrite history. For a public repo or one with a
short history, use `git filter-repo` (preferred over the deprecated
`filter-branch`) or your platform's secret-removal tooling. After
rewrite, force-push with team agreement and ask everyone to re-clone.
5. Document the incident briefly — what leaked, when, how, what was
done. Future-you will want this when a similar mistake happens.
A "delete the key" commit on top is **not safe**. The secret is still
in history and accessible to anyone who clones.
## URLs with embedded credentials
A common slip: pushing with a token-embedded URL writes the token into
`.git/config`:
```
remote "origin"
url = https://user:TOKEN@host/owner/repo.git
```
Fix: after pushing, reset the URL to the credential-free form and let
the credential helper handle auth:
```bash
git remote set-url origin https://host/owner/repo.git
```
Verify with `git remote -v`. The token also lives in shell history and
in any `.bash_history` / PowerShell history file — clear it if the
token is sensitive enough to warrant rotation.
## First push to a new remote
A short checklist when initializing a project:
- [ ] `.gitignore` covers secrets, build outputs, editor state, agent
local state
- [ ] No `.env` (or any `.env.*` other than `.env.example`) in the tree
- [ ] No files >5 MB in the tree
- [ ] `git status` shows only files you mean to commit
- [ ] `git diff --cached` reads cleanly — no surprise content
- [ ] Repo URL on the remote matches the one you intend; no token in
the URL
- [ ] Credential helper is configured (so you don't have to embed tokens
in URLs)
After first push: `git remote -v` should show a clean URL.
## Don'ts (summary)
- Don't `git add .` with unrecognized untracked files in the tree.
- Don't commit `.env`, secrets, tokens, or real credentials — ever, not
even temporarily.
- Don't commit large binaries (>5 MB) without a Git LFS conversation.
- Don't commit generated / cache directories.
- Don't commit real user data or PII.
- Don't try to "clean up" a leaked secret with a delete commit. Rotate
first, rewrite history if needed.
- Don't leave tokens in `.git/config` after a token-in-URL push.
- Don't `--no-verify` to skip pre-commit secret scans.
+233
View File
@@ -0,0 +1,233 @@
---
name: nodejs-project
description: Use in any project with a package.json — task execution SOP from project entry through release, including encoding/line-ending checks that prevent silent file corruption
---
# nodejs-project — AI execution SOP
This is the AI's task-execution sequence in any Node.js / Next.js
project. Each phase is a concrete set of commands or checks the AI runs
**on its own** before declaring the task done. The only points that
pause for the human are flagged explicitly.
## Phase 0 — Project entry
Run on first action in the repo:
```bash
ls AGENTS.md CLAUDE.md package.json .gitignore
node --version
cat package.json | grep -A 20 '"scripts"'
```
- **No `AGENTS.md`** → stop. Ask the human: "this project has no
AGENTS.md; create one before proceeding?"
- **No `.gitignore` or it's <100 bytes** → stop. The project is missing
basic ignore rules; flag before any commit.
- **`node --version` doesn't match what AGENTS.md says** → stop, ask.
## Phase 1 — Task framing
Trigger conditions, in order:
- Task description < 3 sentences AND scope > 1 file → ask for the
5-line spec (`Goal / Why / Done when / Out of scope / Risks`).
- Task touches: `package.json` deps, schema, auth, secrets, production
config, build scripts → confirm scope with human before any edit.
- Otherwise: write the implicit spec into the PR description draft and
proceed.
## Phase 2 — Pre-edit sync
```bash
git status # working tree clean?
git pull --ff-only # remote ahead?
```
- Working tree dirty with unrelated changes → stop, ask.
- `pull --ff-only` fails (diverged history) → stop, ask. Don't
force-pull, don't merge silently.
## Phase 3 — Edit & verify
After each meaningful change run:
```bash
npm run check # if defined
npm test # if defined
npx tsc --noEmit # for TypeScript / Next.js
```
For projects with `build-release` or similar build scripts: do **not**
run them automatically — they produce large artifacts. Run only when
the task is "release."
Failure handling:
- Fix the error, re-run.
- **Same error twice** → stop, surface to human. Don't keep retrying.
Invoke the `debugging` skill — that's what it's for.
## Phase 4 — Encoding & line-ending checks
Run before staging any text file changes. Source code is **UTF-8
without BOM**, line endings follow the project's existing convention
(typically LF, except `.bat` / `.cmd` which need CRLF).
Detection commands:
```bash
# Find files with UTF-8 BOM (EF BB BF) — should be empty output
git diff --cached --name-only -z | xargs -0 -I{} sh -c \
'head -c 3 "{}" | od -An -tx1 | grep -q "ef bb bf" && echo "BOM: {}"'
# Find CRLF in source files that should be LF (skip .bat/.cmd)
git diff --cached --name-only -z | xargs -0 grep -lI $'\r' 2>/dev/null \
| grep -vE '\.(bat|cmd)$'
# Find non-UTF-8 bytes in source
git diff --cached --name-only -z | xargs -0 -I{} sh -c \
'iconv -f UTF-8 -t UTF-8 "{}" >/dev/null 2>&1 || echo "non-UTF8: {}"'
```
Hits → fix before commit:
- BOM in `.js` / `.mjs` / `.json` / `.md` / `.html` / `.css` → strip.
Node `JSON.parse` rejects BOM in `package.json`. Some bundlers ship
BOM into the output and break browsers.
- CRLF in `.js` / `.mjs` / `.ts` / `.tsx` / `.json` / `.md` / `.sh` →
convert to LF. CRLF in `.sh` makes the script silently fail on Linux.
- CRLF in `.bat` / `.cmd` → keep, this is correct.
- Non-UTF-8 bytes (typically GBK on Windows) → re-save the file as
UTF-8 in the editor. This is the most common silent corruption when
AI edits a Chinese-content file on a system with Windows-default
encoding — symptom is "好" appearing as "濂" or similar mojibake.
`.gitattributes` baseline (commit it once per project):
```
* text=auto eol=lf
*.bat text eol=crlf
*.cmd text eol=crlf
*.png binary
*.jpg binary
*.zip binary
```
This forces normalization on commit and prevents future drift.
## Phase 5 — Pre-commit verification
```bash
git status
git diff --cached
```
The AI must read the entire `--cached` diff and answer in its own
output:
1. Build / typecheck pass?
2. Tests pass (or honestly: "didn't run because <reason>")?
3. Files outside the stated scope? List + justify each, or revert.
4. New deps? List them in PR description and Phase 1 confirmation.
5. AI-generated comments restating the code? Delete.
6. End-to-end exercised (for user-visible changes)?
Plus **Node-specific Phase 5 checks**:
- `package-lock.json` in diff but no change to `package.json` deps →
stop. This is usually IDE auto-install. Revert the lockfile diff.
- `package.json` deps changed but no lockfile diff → stop. Run
`npm install` once, commit lockfile in same commit.
- `.env` / `.env.local` / `.env.production` / `*.pem` / `*.key` in diff
→ **stop, do not commit**. Add to `.gitignore` if missing.
- `node_modules/` / `.next/` / `dist/` / `build/` / `out/` in diff →
stop. Gitignore is broken; fix before commit.
- Files >5 MB in diff (`git diff --cached --stat | awk '$3 > 5120'`) →
stop, ask human about LFS or out-of-band delivery.
- Any encoding hit from Phase 4 unresolved → stop.
## Phase 6 — Commit
```bash
git add <specific files> # NOT git add . / git add -A
git commit -m "<area>: <imperative summary under 60 chars>"
```
- Always include `Co-Authored-By: Claude <noreply@anthropic.com>` (or
the project's tool-specific trailer) for AI-assisted commits.
- One topic per commit. "and" in summary → split.
- English message.
## Phase 7 — Push
```bash
git push origin <branch>
```
- First push of a new feature branch: include `-u`.
- Branch is `main` or `dev` → **stop, ask human** before push.
- `--force` push → **stop, ask human**, regardless of branch. Quote the
reason and the branch back to the human.
## Phase 8 — Release (product projects only)
Only run when the task is explicitly "release vX.Y.Z." Skip otherwise.
```bash
# 1. Read project's AGENTS.md "release-bump checklist"
# 2. For each listed file: edit, then verify no stale version remains
git grep -nE 'V?[0-9]+\.[0-9]+\.[0-9]+' -- <changed-files>
# 3. Standard checks
npm run check
npm test
# 4. Commit + tag
git add <changed files>
git commit -m "chore: release vX.Y.Z"
git tag -a vX.Y.Z HEAD -m "<Project> VX.Y.Z"
git push origin <branch>
git push origin vX.Y.Z
# 5. Build
npm run release # or project's build script
# 6. List artifacts
ls -lh release/ # or wherever the build outputs
# 7. STOP — ask human:
# "Artifacts ready: <list>. Sizes: <sizes>. Upload to <distribution
# channel>?"
```
The upload step is **always human-confirmed**. It's the only
externally-visible irreversible action in the flow.
## Where the human pauses
In total, AI stops and asks the human only at:
- Phase 0: missing AGENTS.md
- Phase 1: vague task or scope-sensitive change
- Phase 2: dirty tree or diverged history
- Phase 3: same error twice (invoke `debugging`)
- Phase 4 / 5: encoding / lockfile / secret / large-file anomalies
- Phase 7: push to `main`/`dev` or `--force`
- Phase 8: distribution upload
Everything else is self-running.
## Quick reference
```
[entry] read AGENTS.md → no? stop.
[frame] vague task? → spec. scope-sensitive? → confirm.
[sync] git status / pull --ff-only.
[edit] npm run check / test / tsc. fail twice? invoke debugging.
[encode] no BOM / LF for src / CRLF for .bat / valid UTF-8.
[verify] git diff --cached → 6 questions + Node-specific 5.
[commit] git add by name. <area>: <imperative>.
[push] main/dev/force? stop. else push.
[release] follow project's bump checklist. STOP before upload.
```
+117
View File
@@ -0,0 +1,117 @@
---
name: using-praxis
description: Use when starting any conversation in a Simgreek project — establishes how to find and use praxis skills, requiring Skill tool invocation before ANY response including clarifying questions
---
<SUBAGENT-STOP>
If you were dispatched as a subagent to execute a specific task, skip this skill — your dispatcher already loaded praxis context.
</SUBAGENT-STOP>
<EXTREMELY-IMPORTANT>
If you think there is even a 1% chance a praxis skill might apply to what you are doing, you ABSOLUTELY MUST invoke it.
IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
This is not negotiable. This is not optional. You cannot rationalize your way out of this.
</EXTREMELY-IMPORTANT>
# Using Praxis
Praxis is the Simgreek team's coding agent rulebook — Greek for "practice." It exists because human teammates have been bitten by every shortcut you are about to take. The skills below encode those scars.
## Instruction Priority
Praxis skills override default agent behavior, but **the user's explicit instructions always take precedence**:
1. **User's explicit instructions** (project AGENTS.md, CLAUDE.md, direct chat) — highest
2. **Praxis skills** — override default behavior where they conflict
3. **Default agent behavior** — lowest
If a project's AGENTS.md says "skip the encoding check this once" and a skill says "always check encoding," follow the user. They own the project. You are a guest.
## How to Access Skills
**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its full content is loaded — follow it directly. Never use `Read` on a skill file when `Skill` is available.
**In Codex / Cursor / others:** Skills live as markdown files under `<plugin-root>/skills/`. Read the relevant ones with the file-reading tool.
# The Rule
**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means you must check. If an invoked skill turns out to be wrong for the situation, drop it — but you have to check first.
This includes:
- Before answering a clarifying question
- Before exploring the codebase
- Before "just running git status"
- Before reading docs to understand the project
- Before announcing what you're going to do
The skill check is the **first thing** that happens after you receive a message in a praxis-enabled project. Not the second. Not "after I look around real quick." First.
## Red Flags — These Thoughts Mean STOP
If you catch yourself thinking any of these, you are rationalizing past a skill. Stop, invoke the skill, then proceed.
| Thought | Reality |
|---------|---------|
| "This is just a simple question" | Questions are tasks. Check for skills. |
| "I need more context first" | Skill check comes BEFORE clarifying questions. |
| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
| "I can just check git status / read a file quickly" | Files lack conversation context. Check for skills. |
| "Let me gather information first" | Skills tell you HOW to gather information. |
| "This doesn't need a formal skill" | If a skill exists, use it. |
| "I remember this skill" | Skills evolve. Read the current version. |
| "This is a small change" | Small changes ship the bugs. Use the skill. |
| "The skill is overkill" | Simple things become complex when skipped. |
| "I'll just do this one thing first" | "One thing first" is how skills get bypassed. |
| "This feels productive" | Undisciplined motion wastes time. Skills prevent it. |
| "The user is in a hurry" | Skipping skills makes everything slower, not faster. |
| "I know what that means" | Knowing the concept ≠ following the procedure. Invoke. |
## The Praxis Skill Catalog
Read the catalog before your first action in this project. Match each candidate skill against the current task.
| Skill | When it applies |
|-------|-----------------|
| `git-upload` | Pushing to a remote, first push, adding new file types, leaked secret |
| `nodejs-project` | Any project with `package.json` — task execution SOP including encoding checks |
| `debugging` | Any bug, test failure, unexpected behavior, before proposing a fix |
| `verification` | About to claim work is complete, fixed, or passing |
If multiple apply, use them in order: process skills (`debugging`) before implementation skills (`nodejs-project`); verification (`verification`) before declaring done.
## Skill Priority
When multiple skills could apply:
1. **Process skills first** (`debugging`) — they determine HOW to approach the task
2. **Implementation skills second** (`nodejs-project`, `git-upload`) — they guide execution
3. **Verification last** (`verification`) — before declaring done
"Fix this bug" → `debugging` first, then `nodejs-project` if Node-relevant.
"Push my changes" → `git-upload` first, then `verification` before declaring done.
## Skill Types
**Rigid skills** (debugging, verification): follow exactly. The discipline is the value. Don't adapt away the steps you find inconvenient.
**Flexible skills** (nodejs-project SOP, git-upload pitfall list): adapt principles to context. The SOP is a default; deviate when the context demands and **state the deviation explicitly**.
The skill itself tells you which type it is.
## User Instructions
User instructions describe **what** to do, not **how**. "Add this feature" or "fix this bug" does not mean skip the workflow. The user sets the destination; praxis sets the route.
## What to Do Now
Before your next action:
1. Identify which skills in the catalog above might apply (1% threshold).
2. Invoke each one via the `Skill` tool (or read the file).
3. Follow its checklist.
4. Then proceed.
If the task is something praxis genuinely doesn't cover (e.g., "summarize this article"), proceed without a skill — but the check itself is mandatory.
+139
View File
@@ -0,0 +1,139 @@
---
name: verification
description: Use before claiming work is complete, fixed, or passing — requires running verification commands and reading output before making any success claim; evidence before assertions
---
# Verification — evidence before claims
## The Iron Law
```
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
```
Claiming work is complete without verification is dishonesty, not
efficiency. If you haven't run the verification command in this turn,
you cannot claim it passes.
## The gate
Before claiming any status or expressing satisfaction:
1. **Identify** the command that proves the claim.
2. **Run** it (fresh and complete — not a partial check, not a
remembered previous run).
3. **Read** the full output. Check the exit code. Count failures.
4. **Verify** the output confirms the claim.
- If yes: state the claim **with the evidence**.
- If no: state the actual status with the evidence.
5. **Only then** make the claim.
Skipping any step is lying, not verifying.
## Common claims and what proves them
| Claim | What proves it | What does NOT prove it |
|-------|----------------|------------------------|
| Tests pass | Test command output: 0 failures | "Should pass", a run from earlier |
| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
| Build succeeds | Build command exits 0 | Linter passing, logs look good |
| Bug fixed | Test the original symptom — passes | Code changed, "assumed fixed" |
| Regression test works | Red → green: test fails before fix, passes after | Test passes once after fix |
| Sub-agent completed | VCS diff shows the changes | Sub-agent reports "success" |
| Requirements met | Line-by-line checklist | "All tests pass" |
## Red Flags — STOP
If you catch yourself doing any of these, you're about to make an
unverified claim. Stop, run the verification, then continue.
- Using "should", "probably", "seems to", "I think"
- Saying "Great!", "Perfect!", "Done!" before running anything
- About to commit / push / open a PR without re-running checks in
this turn
- Trusting a sub-agent's success report without diff inspection
- Relying on partial verification (one file checked, claim covers
many)
- "Just this once"
- Tired and wanting the work over
- **Any wording implying success without evidence in this turn**
## Rationalizations
| Excuse | Reality |
|--------|---------|
| "Should work now" | RUN the verification |
| "I'm confident" | Confidence ≠ evidence |
| "Just this once" | No exceptions |
| "Linter passed" | Linter ≠ compiler ≠ tests |
| "Agent said success" | Verify independently |
| "I'm tired" | Exhaustion ≠ excuse |
| "Partial check is enough" | Partial proves nothing about the rest |
| "Different words, so the rule doesn't apply" | Spirit over letter |
## Patterns
**Tests:**
```
✅ Run `npm test` → output: "34 passing" → "All tests pass (34/34)."
❌ "Should pass now." / "Looks correct."
```
**Regression test (red-green):**
```
✅ Write test → run (pass) → revert fix → run (FAIL) → restore fix → run (pass)
❌ "I've added a regression test." (without red-green proof)
```
**Build:**
```
✅ Run `npm run build` → exit 0 → "Build passes."
❌ "Linter passed, build should be fine." (linter doesn't compile)
```
**Requirements:**
```
✅ Re-read the spec → check each line → report gaps or completion
❌ "Tests pass, so we're done." (tests ≠ requirements)
```
**Sub-agent delegation:**
```
✅ Sub-agent reports success → run `git diff` → confirm the changes
exist and are correct → report actual state
❌ Trust the sub-agent report
```
## When to apply
Always before:
- Any variation of "done", "complete", "fixed", "passing"
- Any expression of satisfaction about work state
- Committing, opening a PR, declaring task complete
- Moving to the next task in a multi-step plan
- Delegating verification to a sub-agent (verify their result yourself)
The rule applies to exact phrases, paraphrases, synonyms, and any
implication of success. "Spirit over letter."
## Why this matters
Unverified claims:
- Break the user's trust ("I don't believe you")
- Ship undefined functions or missing requirements
- Waste time on false completion → redirect → rework
Honesty is a core value. The cost of running the verification command
is small. The cost of being wrong is large.
## Bottom line
Run the command. Read the output. **Then** claim the result. Every
time.
-69
View File
@@ -1,69 +0,0 @@
# AGENTS.md — <project name>
<!--
Template. Copy into a new repo and fill the bracketed sections.
Sister file: CLAUDE.md (Claude Code reads that one). Keep them in sync.
Delete sections that don't apply. Keep total length under ~100 lines.
-->
## Project
<One or two sentences. What does it do, who is it for.>
## Run it
```bash
# install
<command>
# run
<command>
# test
<command>
# lint / typecheck
<command>
```
## Architecture
<One paragraph. Where are the entry points, how does data flow, what
are the major modules. Skip diagrams unless they save words.>
Key files:
- `<path>` — <one-line role>
- `<path>` — <one-line role>
## Conventions specific to this repo
<Anything that's not obvious from reading the code. Naming patterns,
where to add new features, what's auto-generated, etc.>
## Language policy
<If this project follows the team's bilingual policy, copy this:>
- Human-facing docs (README, `docs/*.md`, human-fillable templates) are
in Chinese.
- AI-facing files (`CLAUDE.md`, `AGENTS.md`, AI-only templates) are in
English.
- Commit messages, PR titles, branch names, tag annotations: English.
## Don'ts
<Things Codex / Claude / a new contributor has gotten wrong before.
One line each. Add to this list as you discover them.>
- Don't <…>
- Don't <…>
## External resources
<Links to dashboards, related repos, docs, ticket trackers.>
## Sync
When you edit this file, also update `CLAUDE.md` (and vice versa). The
two files describe the same project to different tools.
-69
View File
@@ -1,69 +0,0 @@
# CLAUDE.md — <project name>
<!--
Template. Copy into a new repo and fill the bracketed sections.
Sister file: AGENTS.md (Codex reads that one). Keep them in sync.
Delete sections that don't apply. Keep total length under ~100 lines.
-->
## Project
<One or two sentences. What does it do, who is it for.>
## Run it
```bash
# install
<command>
# run
<command>
# test
<command>
# lint / typecheck
<command>
```
## Architecture
<One paragraph. Where are the entry points, how does data flow, what
are the major modules. Skip diagrams unless they save words.>
Key files:
- `<path>` — <one-line role>
- `<path>` — <one-line role>
## Conventions specific to this repo
<Anything that's not obvious from reading the code. Naming patterns,
where to add new features, what's auto-generated, etc.>
## Language policy
<If this project follows the team's bilingual policy, copy this:>
- Human-facing docs (README, `docs/*.md`, human-fillable templates) are
in Chinese.
- AI-facing files (`CLAUDE.md`, `AGENTS.md`, AI-only templates) are in
English.
- Commit messages, PR titles, branch names, tag annotations: English.
## Don'ts
<Things Claude / Codex / a new contributor has gotten wrong before.
One line each. Add to this list as you discover them.>
- Don't <…>
- Don't <…>
## External resources
<Links to dashboards, related repos, docs, ticket trackers.>
## Sync
When you edit this file, also update `AGENTS.md` (and vice versa). The
two files describe the same project to different tools.
-65
View File
@@ -1,65 +0,0 @@
# Handoff 清单 — <包名或分支名>
<!--
交付前填完整。外部 handoff 一起放进包里;内部 handoff 放进 PR
description。正文中文,技术字段(commit hash、ISO 时间戳等)保留
英文格式。
-->
## 身份信息
- **名称**:<包名或分支名>
- **版本**:<比如 v0.5.0 或 commit sha 或 tag 比如 20260520>
- **生成时间**:<ISO 时间戳>
- **源仓库**:<url>
- **源 commit**:<full sha>
- **作者 / handoff owner**:<name>
- **接收方**:<name 或团队>
## 内容物
- [ ] `README.md` —— 这是什么、怎么用
- [ ] `CHANGELOG.md` —— 跟上一版的差异(首发就写"first release")
- [ ] `manifest.json` —— 机器可读元数据,所有字段都填了或显式 null
- [ ] `VERIFICATION.md` —— 检查了什么、结果如何
- [ ] 数据 / 产物 —— 真正的交付物
- [ ] 脚本 —— 仅限于使用本包必须的脚本
## 验证
- [ ] 记录数 / 文件数与预期一致
- [ ] Checksum 已计算并记录
- [ ] 合理性检查通过(列出来)
- [ ] 不含密钥、`.env`、credential
- [ ] 不含 PII(除非交付协议里就明确包含)
- [ ] 总大小在传输渠道可接受范围
验证报告路径:`<path>`
## 可重现性
- [ ] 已确认有源仓库访问的人能从 `source_commit` 重建产物(写明
谁测的、什么时候测的)
- [ ] 构建 / 生成命令写在 `README.md` 里
- [ ] 外部依赖锁版本
## 来源(AI 协助生成时填)
- 使用的模型:<比如 claude-opus-4-7、gpt-5-codex>
- 人工审核步骤:<人审 / 批准了哪些部分>
- 值得标注的 AI 决策:<半年后产物有问题时会想知道的事>
## 已知限制
<不能用的场景、未覆盖的边界、本版没赶上的后续。具体写。"在我机器
上能跑"不是限制——是发布前要修的问题。>
- <…>
- <…>
## 给接收方的说明
- [ ] 先读 `README.md`
- [ ] 跑验证报告 —— 不通过就停下来联系发送方
- [ ] <X 天>内确认收到
- [ ] 任何意外(缺文件、版本不对、命名异常)<X 天>内反馈给发送方
-49
View File
@@ -1,49 +0,0 @@
<!--
PR description 模板。标题写在 PR 标题栏,不在这里。
标题格式:<area>: <祈使句小结,70 字符以内>。英文。
正文中文。
-->
## Summary(小结)
<一句话说清这个 PR 干了什么。需要的话再加 1–3 条 bullet。>
- <bullet>
- <bullet>
## Why(为什么)
<动机。解决什么问题、落实什么决策、修哪个 bug。如果挂着 issue
或者之前的讨论,链上来。>
## What changed(改了什么)
<列出实际改动,跨多个区域时按区域分组。写事实就行——diff 是真相
来源,这只是地图。>
- `<文件或区域>` — <改动>
- `<文件或区域>` — <改动>
## Test plan(测试方案)
<勾选式 checklist。做了的勾 `[x]`,没做的留 `[ ]` 并在下面解释为什么。
诚实——"没测"可以接受,"声称测了但没测"不行。>
- [ ] 单元测试本地通过(`<command>`)
- [ ] Lint / typecheck 通过(`<command>`)
- [ ] <功能特定的检查>
- [ ] <功能特定的检查>
## Out of scope(范围外)
<你注意到但**显式选择不在这个 PR 修**的东西。帮 reviewer 不要在这些
点上提出来。>
## Notes for reviewer(给 reviewer 的提示)
<让你意外的地方、值得标注的 AI 协作决策、走过的捷径,或者"我考虑
过 X 但选了 Y 因为 Z"。没什么可写就删掉这一节。>
---
🤖 AI 协助完成(Claude Code / Codex)。
-62
View File
@@ -1,62 +0,0 @@
# <项目名>
<一句话。这是什么,用大白话写。>
## 这玩意儿干啥的
<一段话。比 tagline 多点细节。谁会用、解决什么问题、明确**不**做
什么。>
## 快速上手
```bash
# clone
git clone <url>
cd <repo>
# 安装
<command>
# 跑起来
<command>
```
预期输出:
```
<几行用户应该看到的内容>
```
## 开发
```bash
# 测试
<command>
# lint / typecheck
<command>
# 格式化
<command>
```
代码在 `<dir>`。测试在 `<dir>`。架构细节看 [docs/](docs/)(没有就
删掉这行)。
## 配置
<env var、配置文件、密钥。指向 `.env.example` 如果有的话。不写真实
值。>
## 数据来源 / 流向
<仅当不显然时写。输入从哪来,输出到哪去。>
## 相关链接
- <链接>
- <链接>
## License
<Internal / MIT / 等等。>