技能导读 · 2026-11-22

四则技能:译文、原文与因果

这四则守的是四个不同的时刻。会话结束之后看环境,改代码时排顺序,问动机时回到记录,问机制时先建立能开工的模型。

问句里的 ub-model,对应本机技能 ub-mode。译文按当前安装的 SKILL.md 逐段对照。高亮是这一则用来做决定的词。因果是导读,写在对照正文之前。

怎么读

每一对都是同一句式。因:技能要对付的局面。果:它因此规定的做法。先读因果,再读中文,英文原文贴在对应段落后面。

四则都由人点名才运行。disable-model-invocation: true 写在 retro、why、how 的前言里。ub-mode 的本机配置同样默认不自动调用。

  1. retro 因:损耗留在环境里。果:改环境,等你挑选候选。
  2. ub-mode 因:改动会变成补丁。果:先让它工作,再让它正确,然后按实践收尾。
  3. why 因:理由不在当前代码里。果:从提交和讨论里引用记录。
  4. how 因:改之前需要心智模型。果:只读探索一次,再轻度呈现。

retro

回顾一次编码会话,提议改进编码代理的环境。来源:mattpocock/skills,Matt Pocock,MIT。本机文件与快照 abeeaf95 的 skills/engineering/retro/SKILL.md 一致。

为什么需要它

  1. 因一次难会话里,找文件太久、错误本来可以被检查抓住、工具调用很贵、关键信息到不了代理手里。这些摩擦长在仓库和工具上,会在下一次同类任务里重演。

    果retro 读这次会话的原始记录,按严重程度列出环境上的候选改动。它只提议。你挑选之前,什么都不改。

  2. 因实施代理要探索、写代码、排错,上下文压力最大。审查代理拿到的是 diff,探索已经结束。

    果编码标准交给审查代理。实施代理的上下文留给找路和改代码。

  3. 因机械违规有固定形状:句法、禁用 API、导入方式、文件位置。一句散文挡不住它。判断题,例如跨文件是否一致、是否像周围的风格,检查也代替不了。

    果机械违规做成确定性检查:仓库自己的 linter、pre-commit 或 CI。判断题才写进 CODING_STANDARDS.md。已有检查没接上,发现就是接上它。完全没有护栏,本身就是一条发现。

  4. 因AGENTS.md 和 CLAUDE.md 会进入这个仓库里每一个代理的上下文。文件一大,有用的句子就被稀释。不改变行为的句子还占着位置。

    果这两份文件只留导航指针。能变成标准或自动检查的指导搬出去。空操作从臃肿的指导文件里删掉。

  5. 因有些信息本来就存在,只是代理读不到:开发服务器日志、第三方服务的只读数据。

    果把日志接到代理读得到的地方,或开放只读访问。信息获取补上之后,下一轮才不用猜。

关键词

  • retrospective回顾
  • environment环境
  • navigation pointer导航指针
  • guardrail护栏
  • mechanical机械的
  • judgement call判断题
  • context pressure上下文压力
  • reviewer agent审查代理
  • tool economy工具经济
  • no-op空操作
  • information access信息获取

对照正文

对一次编码会话做回顾。

Conduct a retrospective on a coding session.

用户要求做一次回顾。你要提议的是编码代理的环境该怎么改进,好让以后的运行更好。

The user has asked for a retrospective. You are suggesting improvements to the coding agent's environment to improve future runs.

步骤

  1. 调用 Skill 工具,加载 writing-for-agents,取得写作风格指南。

    Call the Skill tool with writing-for-agents for the writing style guide.

  2. 阅读用户指定的那次会话的原始材料。这可能意味着在这台机器上搜索会话日志。用户没有指定会话时,默认用当前这次。

    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.

  3. 在下面这些类别里寻找改进候选。

    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.

自动检查

自动检查:有没有自动检查能抓住代理犯过的错?Lint、类型、测试、文件系统 linter?先读仓库自己的检查命令,也就是 package.json 或构建工具里的 lint / check 脚本,以及它的 CI。已经存在、只是没接上或静默坏掉的检查,才是发现。重新发明一套不算。完全没有护栏的仓库本身就是一条发现:没有 pre-commit 钩子,也没有 CI 任务去跑 lint、类型检查和测试。未经 lint 的仓库是一处一直敞开的遗漏。别把它当成中性的默认状态。代理犯了自动检查本可抓住的错,或者仓库根本没有护栏时使用。

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.

全局 AGENTS.md

全局 AGENTS.md:有没有指导说明应该挪到编码标准或自动检查里?仓库里或用户全局范围里的 AGENTS.md 特别大时使用。

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.

工具经济

工具经济:代理有没有做过本可以收束的昂贵工具调用?有没有特别费 token 的自定义工具,包括 CLI 和 MCP?代理做了昂贵的工具调用时使用。

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:这两份文件会被推进任何在这个仓库里工作的代理的上下文。要用得极其节制,通常只放指向其他文件的导航指针。

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:这份文件在审查时读,实施时不读。标准文件超过 1000 行时,加上指向文档目录的导航指针。

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.

技能:文档可以做成技能,因为技能的 description 会进入代理的上下文;用户点名才运行的命令也做成技能。写作遵循 writing-for-agents 里的建议。

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 指的就是这一则。

为什么需要它

  1. 因一次改动如果就地打补丁,决策会散落,数据形状会后补,非法状态会漏进后面的逻辑。

    果先让它工作。一个决策只住一处,先定数据形状,先写会按预期失败的测试,能减掉的复杂度先减掉。

  2. 因能跑的代码仍可能修在症状上。测试如果绑在内部形状上,重构一来就碎。复杂度、重复和没被杀死的变异,眼睛守不住。

    果再让它正确。先复现再修原因。一小段做完并核对,再开始下一段。测试用户看得见的行为。用 crapper、dryer、mutator 把门槛变成可重复的门。

  3. 因两个修法若共享同一个前提,又在同一道门上失败,继续修只是在给这个前提打补丁。

    果把前提写成一句话,数清哪些角色承担失衡,拿掉这项分配。做完之前不再开下一个修法。

  4. 因做完的证据如果只留在对话里,下一次无从核对。主线程塞满过程之后,后面的判断会变钝。

    果按实践收尾。记下每个动作和理由。大块工作送出去,主线程只留摘要。小步、有序地提交,写明为什么、改了什么、如何证明。

关键词

  • First Make it Work先让它工作
  • Then Make it Right再让它正确
  • Practice实践
  • one decision一个决策只住一处
  • data shape数据形状
  • failing test失败的测试
  • premise前提
  • illegal state非法状态
  • pure function纯函数
  • idempotent幂等
  • root cause根因
  • behavior行为
  • CRAP复杂度与覆盖率的分数
  • context window上下文窗口

对照正文

写代码或改代码时遵守这套收短了的原则。每一次改动都遵循:先让它工作,然后让它正确,再按实践做。用户运行 /ub-mode,或要求这套收短了的原则时使用。

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。

为什么需要它

  1. 因打开文件只能看见现在的形状。选择、被放下的方案、后来的每次改动,写在引入它的提交和 PR 讨论里。代码走读会把残留的形状当成理由。

    果why 从记录回答。读引入目标的提交,以及后来的每一次改动。引用作者写过的话。自己的推断标成推断。记录没有回答的部分要说出来。

  2. 因同一段代码还有另一个问题:它运行时怎么走,东西该放在哪一层。

    果运行机制、分层和归属交给 how。why 守住动机、取舍、回归和有数据支撑的阈值。

关键词

  • record记录
  • commits提交
  • PR discussionsPR 讨论
  • inferences推断
  • tradeoffs取舍
  • 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.

从记录回答,不从代码回答。阅读引入这个目标的提交和 PR 讨论,以及后来的每一次改动。线索稀薄时再看其他来源。引用作者写过的话,把自己的推断标成推断,并说明记录没有回答什么。

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.

how

回答“X 怎么工作”,在改动之前走读代码,并回答放置、归属和分层。来源:backnotprop/pstack 的 skills/how/SKILL.md,Lauren Tan,MIT。本机文件与该仓库当前正文一致。动机交给 why。

为什么需要它

  1. 因改一个子系统之前,需要一份陌生的资深工程师能带走的心智模型:架构、运行路径、东西该放哪、哪一个包拥有它、这一层对不对。

    果how 用一次探索把这个模型写出来。写到足以自信地开始干活。主线程呈现结果,只为清楚或为对话里的上下文做轻度编辑,不做实质性重写。

  2. 因这段探索如果堆在正在改代码的线程里,上下文会被找路占满。

    果探索交给只读的通用子代理,一次走完探索和说明。没有子代理工具时,自己探索并写下来。

  3. 因范围含糊时如果停下来等确认,探索会推迟到用户已经能纠正的时候才开始。动机和运行路径混在一篇里,两边都会变浅。

    果先写出自己的理解,再探索。用户可以改道。动机交给 why。

关键词

  • how does X workX 怎么工作
  • mental model心智模型
  • architecture架构
  • ownership归属
  • layering分层
  • read-only subagent只读子代理
  • why动机,另一则技能

对照正文

用于“X 怎么工作”、改动之前的代码走读,以及放置、归属、分层的问题:“这该住在哪”“哪个包拥有它”“这一层对不对”。说明子系统架构、运行时流程,以及上手用的心智模型。动机用 why。

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.

1. 说明

派出一个只读的通用子代理,一次走完探索和说明。在 Cursor 里用 Task,subagent_type: generalPurpose,readonly: true。在 Claude Code 里用 Agent(subagent_type: general-purpose)。在 OpenCode 里用 task(subagent_type: general)。在 Codex 里用 spawn_agent。如果你的运行环境没有子代理工具,例如没有扩展的 Pi,就自己探索并写下来。把用户的问题和下面这段简报交给它:

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.