Read the primary sources for the session the user specifies. This may mean searching through session logs on this machine. If the user doesn't specify a session, default to the current one.
在下面这些类别里寻找改进候选。
Look for candidates for improvement in these categories.
Navigation: how easy was it for the agent to find the right files? Are there hidden dependencies between files? Would a navigation pointer make it easier? Use when the session took a long time to find a piece of information.
Automated checks: are there automated checks that could catch errors the agent made? Linting, typing, tests, filesystem linters? Read the repo's own check command first (its package.json/build-tool lint/check scripts, its CI workflow), so a check that already exists but sits unwired or silently broken is the finding, not a reinvention. A repo with no guardrail (no pre-commit hook and no CI job running its lint/typecheck/test command) is itself a finding: an un-linted repo is a standing missed opportunity, not a neutral default. Use when the agent made a mistake an automated check could have caught, or the repo has no guardrail at all.
编码标准
编码标准:要不要给审查代理一条新规则?已有规则该删掉,还是该写清楚?先给违规分类。机械的违规,包括固定的句法模式、禁用的 API、导入形状、文件位置规则,用确定性检查收场:仓库自己的 linter 里加一条自定义规则,或新的 pre-commit 钩子,或新的 CI 任务,选这个仓库的语言和现有护栏里最便宜的那种。默认去做检查。把 CODING_STANDARDS.md 留给真正的判断题:跨文件是否一致、“像周围的风格”,以及任何护栏永远代替不了的事。审查代理没能抓住一个错误时使用。
Coding standards: should the reviewer agent be given a new rule to enforce? Should an existing rule be removed or clarified? Classify the violation first: a mechanical one (a fixed syntactic pattern, a banned API, an import shape, a file-location rule) gets a deterministic check, full stop: a custom rule in the repo's own linter, a new pre-commit hook, or a new CI job, whichever the repo's language and existing guardrail make cheapest. Default to building the check over writing the rule. Reserve CODING_STANDARDS.md for genuine judgement calls (cross-file consistency, "matches the surrounding style," anything no guardrail could ever substitute for). Use when the reviewer agent failed to catch a mistake.
Global AGENTS.md: are there any steering instructions that should be moved to coding standards (or automated checks) instead? Use when the AGENTS.md file is particularly large, in the repo or the user's global scope.
Tool economy: did the agent make expensive tool calls that could be streamlined? Is there any custom tooling (CLIs, MCPs) that is particularly token-inefficient? Use when the agent made an expensive tool call.
空操作
空操作:在指导文件里找那些不改变代理行为的说明。指导文件又大又难用时使用。
No-ops: look for instructions in steering files that don't modify the agent's behavior. Use when the steering files are large and unwieldy.
Information access: look for opportunities to increase the agent's access to information. Teeing dev server logs, readonly access to third-party services. Use when a crucial piece of information was not available to the agent.
按严重程度把这些候选呈现给用户。
Present these candidates to the user, in order of severity.
实施与审查
所有工作都经过两个阶段:实施和审查。实施代理的上下文压力最大。它负责探索、写代码、排错。
Remember that all work goes through two stages: implementation and review. The implementation agent has the most context pressure. They are responsible for exploration, writing code, and debugging failures.
审查代理的上下文压力最小。它收到一份 diff,不需要探索。它常常也不需要写代码或排错。
The review agent has the least context pressure. It receives a diff, so no exploration needed. It often does not need to write code or debug.
因此,施加编码标准的责任在审查代理,不在实施代理。
This means that the review agent should be responsible for imposing coding standards, not the implementation agent.
CLAUDE.md/AGENTS.md: these files are pushed to the context window of any agent working in this repo. They should be used incredibly sparingly, usually only for navigation pointers to other files.
CODING_STANDARDS.md: this file is read during review, not implementation. Add navigation pointers to docs folders if the standards file gets more than 1,000 lines long.
文档:把文档当参考文件,由其他文件指向它们。写新文档之前先找已有的。
Docs: use docs as references files, pointed to by other files. Look for existing docs before writing new ones.
Skills: use skills for docs (since their description goes into the agent's context window), or for user-invoked commands. Follow the advice in the writing-for-agents skill.
ub-mode
写代码或改代码时遵守一套收短了的原则。每次改动都是:先让它工作,再让它正确,然后按实践做。来源:unclebob/ub-mode,Robert C. Martin,MIT。本机文件是 ~/.codex/skills/ub-mode/SKILL.md。问句里的 ub-model 指的就是这一则。
Follow the reduced principles when writing or changing code. Every change follows First Make it Work, then Then Make it Right, then Follow Practice. Use when the user runs /ub-mode or asks for the reduced principles.
每一次被要求做改动,都遵循:先让它工作。然后让它正确。按实践做。
Every time you are asked to make a change follow: First Make it Work. Then Make it Right. Follow Practice.
先让它工作
First Make it Work
懒惰协议
一个决策只住在一处。
One decision lives in one place.
发出能解决问题的最小编辑。
Ship the smallest edit that solves the problem.
基础思考
写逻辑之前,先把数据形状定对。
Get the data shape right before you write the logic.
先做对后面每一个阶段都有帮助的事。
Do first whatever helps every later phase.
如果并发写入会有影响,就不要共享状态。
If a concurrent writer would matter, do not share state.
TDD
改代码之前,先写会失败的测试。
Write the failing test before you change the code.
看着它因为你预期的原因失败。
See it fail for the reason you expect.
做让它通过的最小改动。
Make the smallest change that makes it pass.
如果一份诚实的测试不切实际,就不要写一份糟糕的测试。
If an honest test is impractical, do not write a bad one.
从第一原则重新设计
不要把新需求栓到旧设计上。
Do not bolt a new requirement onto the old design.
问问假如它从一开始就在,你会建成什么样。把这个想清楚,再分成几块交付。
Ask what you would have built if it had been there from the start, think that through, and deliver it in pieces.
攻击前提
当两个修法共享同一个前提,又在同一道门上失败时,把这个前提写成一句话,并数清哪些角色承担着失衡。
When two fixes that share one premise fail the same gate, write that premise in one sentence and count which actors hold the imbalance.
拿掉这项分配。
Remove the assignment.
做完这件事之前,不要开始下一个修法。
Do not start another fix until you have done that.
先减再加
加任何东西之前,先把复杂度拿出去。
Take complexity out before you add anything.
面向结果的执行
瞄准你能够核对的终态。
Aim at the end state you can check.
中间断开是允许的,条件是你事先计划了,并且能撤销。
A break in the middle is allowed when you planned it and can undo it.
建造杠杆
如果这份工作不能一眼看明白,就建造那个去做它的工具。
If the work is not obvious at a glance, build the tool that does it.
先用手做一单位,再让工具对准这一单位。
Do one unit by hand, then make the tool match that unit.
给领域建模
把领域放进一种让非法状态无法出现的结构里。
Put the domain in a structure that makes the illegal states impossible.
维持一份领域术语表。
Maintain a glossary of domain terms.
如果代码已经清楚,而且改动是局部的,就留着它。
If the code is already clear and local, leave it.
边界纪律
在数据进入的地方检查它。
Check the data where it enters.
到了里面,信任它。
Inside, trust it.
把业务逻辑留在纯函数里。
Keep the business logic in a pure function.
类型系统纪律
让非法的值无法被写出来。
Make the illegal value impossible to write.
外部数据在进来的地方解析一次。
Parse outside data once, where it comes in.
不要让编译器沉默。
Do not silence the compiler.
让操作幂等
跑两次,或者在中途崩溃之后再跑,都停在同一个状态。这就是幂等。
Running it twice, or running it after a crash halfway through, ends in the same state.
共享状态在序列化之前先分开
如果它们不需要同一份可变的东西,就各给一份。
If they do not need the same mutable thing, give each its own.
如果需要,只允许一个写入者,并把这一点做进结构里。
If they do, allow one writer, and enforce that in the structure.
再让它正确
Then Make it Right
修根因
复现它。
Reproduce it.
修原因。
Fix the cause.
只把崩溃藏起来的守卫,不算修复。
A guard that only hides the crash is not a fix.
把工作排成可验证的小段
做完一小段,核对它。
Finish one small unit and check it.
然后开始下一段。
Then start the next.
测试行为,不测试实现
测试按用户调用代码的方式去调用,并核对用户会看见的结果。
The test calls the code the way its user does and checks the result that user would see.
假如每个函数都返回空,测试仍然能过,就把这个测试丢掉。
If the test would still pass when every function returned nothing, throw it out.
Crapper
使用 crapper 工具。
Use the crapper tool.
把每个函数的 CRAP 降到 10 以下。办法是拆开它,或给它写测试,或两样都做。
Reduce each function under CRAP 10 by splitting it, by testing it, or both.
考虑 case 语句值不值得拆小。
Consider whether case statements are worth reducing.
Dryer
用 dryer 工具消掉相似度达到 0.8 或以上的重复。
Use the dryer tool to eliminate duplication that rank 0.8 or above.
Mutator
使用 mutator 工具。
Use the mutator tool.
补上没覆盖到的。
Cover the uncovered.
杀掉活下来的变异。
Kill the survivors.
删除死代码。
Delete dead code.
重构
先钉住代码在做什么。
Pin what the code does.
再改结构。
Change the structure.
证明行为没有变。
Prove the behavior did not change.
实践
Practice
留一份日志
为你采取的每一个动作,以及你采取它的理由,留一份日志。
Keep a log of every action you take and the reason you took it.
完成时报告这份日志。
Report that log upon completion.
守住上下文窗口
让主线程保持小。
Keep the main thread small.
把大块送去别处,只把摘要留在上下文窗口里。
Send the bulk elsewhere, and keep the summary.
清理工作树
找出可以安全移除的东西,确认仍在使用的东西都不需要它,然后收回磁盘。
Find what is safe to remove, confirm nothing still in use needs it, then reclaim the disk.
未提交的工作等一个决定。
Uncommitted work waits for a decision.
提交并推送
经常提交,提交要小,并且有顺序。
Commit often, in small ordered commits.
每一次提交都说明为什么、改了什么、你如何证明。
Each commit says why, what changed, and how you proved it.
结束时推到主线。
Push to the main line at the end.
why
回答“为什么 X 是这样”“为什么当时选了 Y”,以及设计理由、回归、事后分析和有数据支撑的阈值。来源:backnotprop/pstack 的 skills/why/SKILL.md,Lauren Tan,MIT。本机文件与该仓库当前正文一致。运行机制交给 how。
用于“为什么 X 是这样工作的”“为什么我们选了 Y”、设计理由、回归、事后分析,或有数据支撑的阈值。返回一份带引用的读法,内容是决策和取舍。运行时行为用 how。
Use for "why does X work this way", "why we picked Y", design rationale, regressions, postmortems, or data-backed thresholds. Returns a cited read on decisions and tradeoffs. Use how for runtime behavior.
Answer from the record, not the code: read the commits and PR discussions that introduced the target and each later change, and other sources if the trail is thin. Cite what the authors wrote, mark your own inferences as inferences, and say what the record does not answer.
Use for "how does X work", code walkthroughs before changing something, and placement / ownership / layering questions ("where should this live", "which package owns this", "is this the right layer"). Explains subsystem architecture, runtime flow, onboarding mental models. Use why for motivation.
探索代码库,回答“X 怎么工作”。
Explore the codebase to answer "how does X work?" questions.
范围含糊时,先说出你的理解,再探索。用户可以改道。
If the scope is ambiguous, state your interpretation and explore. The user can redirect.
Spawn one read-only general-purpose subagent that explores and explains in one pass: Task with subagent_type: generalPurpose and readonly: true in Cursor, Agent in Claude Code (subagent_type: general-purpose), task in OpenCode (subagent_type: general), spawn_agent in Codex. If your harness has no subagent tool, as in Pi without an extension, do the exploring and writing yourself. Give it the user's question and this brief:
You are writing an architectural explanation for a senior engineer. Explore the codebase and write an explanation that a senior engineer unfamiliar with this area could read and walk away with a solid mental model. They should understand the architecture well enough to start working in it confidently. You have read-only access to the codebase.
2. 呈现
呈现子代理的输出。为了清楚,或为了补上对话里的上下文,做轻度编辑可以。不要实质性地重写它。
Present the subagent's output. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it.