skill-rails

Skill Rails

设计一个独立的技能，作为小型规范源代码包，并在用户提出要求时构建它。需要表达含义的内容由散文承载，保留给 AI 或用户；声明的工具则承载可精确判定的内容。

工作周期

start or resume
 ├─ new package ──→ references/new-package.md: where the source goes, whether to keep maintenance documents, how the work will run
 └─ existing package ──→ read the project's recorded state
        │
        ▼
SOURCE  design and refine with the user, over as many passes as needed; nothing is built      § Author or change one target
        ├─ a change alters what another AI decides or does ──→ REVIEW   § Review before you conclude
        │     read it as its user would and hold it to this skill
        │     a finding ──→ fix at the owner, then REVIEW again from the entry
        │     a pass that finds nothing left to fix ──→ back to SOURCE
        │  the user asks to build or test                                § Build, test, and deliver when the user asks
        ▼
ROUTE   recorded? ── no ──→ references/delivery.md: user chooses among routes A–D ──→ record it
        │
        ▼
BUILD   source ──→ the standalone skill folder the route needs      references/build-and-test.md
        │  build or check returns ERROR ──→ stop and follow its nextAction
        │  when a test was asked
        ▼
TEST    put it in place on this machine by the route ──→ a fresh AI uses it
        │  the run falls short ──→ keep what it showed and resolve the cause at its owner; a source fix returns to SOURCE
        ▼
back to SOURCE: a later change is a source change; built and installed copies stay behind until they are rebuilt and put in place again, so say so

从用户当前所处的环节加入工作周期。用户选择或之后要求推荐的维护文档时，使用 references/project-docs.md 为其设置文档。作出编写或维护方面的判断前，先阅读 references/skillEvolutionMethod.md（方法）的 §§0–0.1，根据当前决策从其路由表中选择后续章节，并依据 §2 确定深入程度；该方法生成的 skillEvolutionMethod.index.json 仅用于定位字节范围，不定义任何含义或任务清单。

从规范源代码开展工作

• 修改拥有相应行为的清单、目标描述符、入口、模块、参考资料、工具或记录文件，绝不修改生成的输出或运行时状态；带有 .skill-rails-build.json 的文件夹属于生成内容，绝不可手动编辑。
• 仅声明目标实际使用的模块、参考资料、工具和记录文件。构建会对未知字段、未声明路径、根目录越界和输出冲突采取失败关闭策略。清单路径相对于清单所在位置，而其目录是所有源路径必须保持在内的根目录；描述符的文件路径相对于该描述符；记录声明的输入和输出相对于项目；scripts/skill-rails-cli/contracts/ 中的封闭模式定义了字段。
• 使用准确的 ID 和路径。不要推断源文件未声明的要求、检查、效果或因果关系。
• 在后续决策依赖此前对源文件的阅读，或准备将其作为最终结论报告之前，重新阅读所依据的源文件并确认其内容仍然成立；仅当这些文件自上次阅读后未发生变化时，才可跳过重读。如果过时的输入或输出会导致答案失效，应重新阅读当前源文件，而不是沿用旧答案。

编写或更改一个目标

1. 编辑前先检查：当软件包已存在时，使用 CLI 的 inspect（仓库操作）按准确 ID 查询软件包或目标，然后检查要修改的所有者及其使用者。如果目标实际上会读取、运行或写入未声明的内容，应在其规范所有者处添加声明。
2. 说明要减轻的用户负担、必须由 AI 或用户保留的含义、可观察到的结果，以及不在范围内的内容。
3. 选择能实现目标的最小形式，并结合 确定工具应负责的内容、拆分工作 和 编写供另一个 AI 执行的散文 来编写；为每个目的、规则、声明、工具和证据主张指定唯一的规范所有者。
4. 当一个目标的散文将某个产物、决策、恢复、清理或后续执行者责任交给另一个目标的执行者时，应阅读每个相关目标的入口，并确认接收方的义务可通过其自身入口、参考资料或导入模块访问；仅当共享导入的模块本身陈述了该义务时，共享导入才满足此要求。若这些文本未说明交接，则应视为不存在，不得自行推断。
5. 使用 结论前审查 审查更改。凡属于该审查 适用情况 的更改，均须运行该审查后才算完成，无论更改看起来多么细微；报告中应说明由谁审查以及审查结果。

决定工具应负责什么

工具是你写入源代码的脚本；构建过程会将其打包到技能的 scripts/ 文件夹中，AI 会运行它，而不是阅读它。如果某个步骤的结果可以根据工具能够读取或接收的输入（文件、git 状态、AI 已掌握的值）精确确定，并且出错会改变写入的内容、下一步要做什么或工作是否通过验收，就把这一步交给工具。凡是需要理解和判断的内容，都保留在文字说明中：目的、适用情况、是否已完成或是否足够好、某项操作是否安全或获准，以及权衡取舍。如果某一步两者都需要，就在此处拆分：AI 作出判断并传给工具，由工具完成精确的剩余工作——汇总 AI 分类的内容，写入 AI 决定的状态。工具能保证一致，但并非万无一失：它只能确定自己检查的内容。

权衡工具能省去什么，以及它会带来什么。工具能省去 AI 原本需要手动完成的精确工作——遍历大量文件、计数、匹配确切格式、生成 ID、根据固定规则检查已完成的文件——以及这类工作容易引发的错误，无论错误是可能发生还是已经出现：格式错误、遗漏项目、过时的写入、同一规则的两个副本逐渐不一致。工具也会增加需要维护正确的代码、需要运行的命令，以及文字说明必须处理的失败情况；它对用户或现有文件施加的任何迁移成本也应计入。工具使用方便，并不意味着可以擅自更改用户依赖的格式，因此除非请求已经涵盖此类迁移，否则应先与用户商定。依赖精确结果的项目数量、运行次数和读者越多，失误的代价越高，使用工具的理由就越充分——一次运行处理数千个文件，也足以证明使用工具的合理性，正如每天都要重复的操作一样。反之，如果结果足够灵活，细心的读者就能正确处理，理由就越不充分。如果 AI 必须重述判断来填入工具的输入，结果却只是它自己本来也能生成的内容，那么工具增加的只是流程，而非确定性。

例如：在不同阶段之间传递的固定字段状态文件，如果遗漏会误导下一阶段，就可以使用一个共享检查器；没有固定不变量的自由文本不需要工具；对五十张收据求总和的技能，可以用工具计算总额，同时由 AI 决定每张收据的类别。

在清单的 tools 中声明工具，并在每个打包该工具的目标中列出它。对于必须写入由其他人共同编辑的文件、且不能丢失他们更改的判断结果，目标核心的 record 可能更合适。在编写或更改工具或 record，或调用它的步骤之前，请先打开 references/tools.md。

拆分工作

将入口保持为最精简、完整且每次都会读取的契约：理解每个分支所需的背景和意图；目的、使用触发条件和操作边界；每个分支都会使用的规则，或指向其规范归属位置的无条件指针；当前输入；完成证据；以及对于每个其他文件，说明在打开之前即可根据当前任务判定的精确打开条件——用入口自己的措辞，表述为下一步操作、已确认的状态或提出的问题；如果工作分阶段进行，先给出流程图（写出另一个 AI 能据此行动的文字）。使用 frontmatter 中的 description 说明这项技能的作用，以及哪些请求应该启动它；措辞应贴近用户的说法，并足以将它与相邻技能区分开来；将工作流程放在正文中。

如果一次运行可以根据当前任务或阶段判断暂时不需要某个内容块——例如某阶段开始前的细节，或罕见情况的处理方式——而节省的阅读量超过导航和重读的成本，就将该内容块移到单独的文件中。无论内容多长，都不要拆开必须一并判断的内容。

只有此目标读取并负责维护的内容，才是目标自有的参考资料；在描述符的 references 中以相对于目标的路径声明，并放在 references/<file name> 中交付。其他目标也会读取的内容，或由此目标之外的对象负责维护的内容，是按 ID 导入的软件包模块；当第二个目标需要某份参考资料时，将其提升为模块，并重新指向所有读取者。构建过程会将模块复制到每个使用它的技能中，因为每个已安装的技能都必须能独立运行；由于读取内容会消耗上下文，同一对话中通过另一项技能再次读取模块也会再次消耗上下文。确保每个使用者都会始终读取的模块内容完整而精简，并将只有部分使用者需要的内容移到某一步骤需要时才打开的模块中。

对于可以独立启动的职责，应创建单独的技能——它们有自己的触发条件、自己的会话，或需要与被检查的工作分开进行检查，例如由未参与编写的会话进行审查。如果各阶段总是在同一次工作中连续进行，且没有任何阶段需要自己的入口或此类单独检查，就将这些阶段保留在一项技能中，并在每个阶段开始时加载该阶段的细节。交接给另一项技能时，指出该技能的名称及它应该查找的产物，绝不要指向其文件夹中的路径。

写出另一个 AI 能据此行动的文字

让刚开始工作的 AI 明白目标、目标为何重要，以及选择行动路径时应遵循的标准和边界；只有当顺序、状态、外部影响或审批会改变结果时，才规定固定顺序；说明哪些事情从性质上就不得发生，以及原因，而不是给出封闭清单；并设置一道错误转向无法越过的关卡，可以是工具的检查，也可以是审查者能够验证的边界。读者会把列出的每个步骤或事项都视为必须履行的职责，负荷过重时会漏掉其中一些；遇到清单未列出的情况时，也无从推理。

将一次判断所需的内容放在一起——作出判断时应同时给出其目的、标准、边界和示例；始终用同一个名称指代每件事，并说明 this 或 as needed 这样的词具体指向什么。读者无法可靠地从分散的提及中拼凑出意图，会把两个名称理解成两件事，并用自己的猜测填补含糊的措辞。

如果技能自身的结果可能偏离其标准——例如文档、计划或审查——就应在报告完成之前，将结果与这些标准核对：对于《决定工具应负责什么》中给出的工具，用该工具进行检查；其他情况则根据标准重新阅读。结果可能偏离标准的地方，就是设置关卡的地方。 先呈现整体，再说明各部分。读者从文件顶部开始阅读，有时只看第一屏，并按照可见的顺序继续阅读。只要文件的各部分共同构成一个整体——依次推进、返回或在后续会话中恢复的阶段、彼此交接工作的技能、一个流程中的步骤、相互依赖的部分——就应先用简短的示意图呈现整体，再解释任何部分：标出每个部分的规则所在章节或文件；将工作必须通过的每项检查（例如评审或验证）作为独立部分；并用文字说明每次转换从哪里开始、由什么触发、通向哪里，也包括检查失败时的转换。这样，任何路径都不会只依赖线条或箭头的位置来表达，因为读者是逐行阅读文字图示的。随后，章节按照示意图中的顺序排列，并沿用其中的名称，使示意图成为章节索引，而不是放在章节旁边做摘要：每次转换都指向负责其细节和例外情况的章节，绝不引导读者执行相关条件所禁止的操作；多个部分共用的规则只写一次，放在这些部分之前，或放在它们共同指向的位置。若整体能用一个简短列表表达，就无需在列表之外另画示意图。将顺序散落在段落中，会让每位读者各自重组出不同的顺序，而末尾的步骤通常是检查，也最先被删掉。

让每个内容块都采用最适合读者阅读的形式——用散文说明目的、理由和判断；只有必须遵循顺序时才用编号列表；无先后顺序的一组内容用项目符号；对多个事物按相同属性进行比较时用表格；示意图、模板或精确格式用代码块；而对于读者必须随时掌握进度的长流程，则用清单，让读者复制到自己的工作中并逐项勾选。每个章节只承载一个阶段或一种判断，并用其他地方也会使用的措辞，写明该章节要做什么或决定什么。整个软件包中的标题、标签和强调格式应保持一致：读者从打开的第一个文件中了解布局，并会在下一个文件中寻找相同布局；如果什么都强调，就等于什么都没强调，因此只强调遗漏后会改变行为的内容。以某个条件为触发的文件，应以一行文字说明该文件负责什么以及何时阅读；较长的文件则应在顶部列出各章节，因为读者可能只预览文件顶部。技能为后续读者撰写的文档也应采用同样的形式，并由技能通过以下示例给出。

与其告诉读者某种形式，不如展示出来；读者对照示例复制的准确度更高，因此只要某种形式会重复出现，就应展示出来：

parallel kinds of one thing  → a block per kind, the same fields in each      none gets merged or dropped
a result that needs judgment → one example, with what in it is fixed marked   a small template
a result that must match     → the form itself, its fields and order fixed    a large template, or the tool that prints it

例如，有两种模式的技能应分别为每种模式提供独立代码块：## Review 和 ## Fix，而不是用一段文字同时描述两者；每种模式都包含相同的字段，例如 When、Produces 和 Stops when，字段名称由该技能自行规定。

在以下每个时机继续编写之前，先应用 references/skillEvolutionMethod.md 的 §5、§§8.3–8.4 和 §9：将指导内容整理成案例列表之前；添加规则、例外情况或工具来修补故障之前；同一句话需要第三次修订时；以及评审没有指出具体失败场景、只说“可能会造成混淆”时。

在完成前进行审查

草稿往往会偏向最容易写的内容，而作者阅读时带有下一位 AI 不会具备的意图。在你宣布更改完成或开始构建前，应再次依据本技能的标准进行审查，作为一道屏障。

• 何时进行：更改会影响另一个 AI 的决策或行动时——新增目标、修改标准或边界、新增或修改工具或调用该工具的步骤、移动文件边界。拼写或措辞修改若不改变目标、权限和行为，则无需审查；路径变更若会影响读取、写入或运行的内容，则需要审查。
• 像使用者那样阅读，采用本方法的阅读测试（§8.4）：亲自完成这次阅读。从更改目标的规范入口开始，遵循其声明的阅读条件，仅使用实际使用该内容的 AI 会获得的输入；针对一两个现实任务，追踪源文告诉该 AI 要做什么、跳过什么，以及哪些内容仍未知。只认可文本实际写明的内容，而非你的本意。这项阅读基于现有源文，无需构建或安装；它属于完成更改的一部分，并非用户要求的测试，因此即便用户要求不进行构建或测试，也仍要执行。如果追踪到的行为偏离了预期，说明源文缺少条件、理由或负责人。
• 按本技能的标准检查：依据 确定工具应负责什么、拆分工作 和 编写其他 AI 可据以行动的文本 检查更改，并检查这些部分之间没有任何单一部分负责的内容：两个位置对同一步骤的要求相互冲突，或某句话阻止了另一处要求的行为。
• 发现问题时，指出其所在位置、会导致的误读或失败，以及原因；没有具体情境，仅说“可能造成混淆”不算发现问题。没有发现问题也是有效结果。
• 在责任源头修复，而不是修复症状出现的位置：缺少的条件应补到需要它的步骤中，读者误解的事实可能应由工具说明；删减或澄清优于添加规则。修复后，按上述方式从入口重新审查，因为修复可能影响未直接修改的文本。若某次审查没有发现待修复的问题，就停止；若同一句话需要第三次修复，应依据方法 §9.2 判断缺少的是什么，而不是继续改写。
• 另一位审查者：如果用户提出要求，也应让另一位 Agent 参与审查——可以是子 Agent，也可以是通过用户运行的协调器启动的 Agent。如果错误更改的代价高昂，或修复总是在同一前提上失败，应在报告中提出建议，而不是未经请求就启动审查者。按照方法 §10 的说明向其介绍背景，并权衡其发现：完整提供背景和意图，不要透露你预期的结果或怀疑的问题；让其仅根据源文和输入追踪任务。
• 构建验证以及工具保留的任何开发测试，都是针对精确部分的屏障；本审查则关注 AI 如何使用这些部分。两者都不能取代已安装技能的测试；只有用户提出要求时才运行该测试。

仅在用户要求时构建、测试和交付

没有构建目录的源代码包，就是创作工作的完整成果；你可以根据用户的反馈反复完善，直到满足需求。用户要求更改技能的功能时，这属于源代码更改，即使已有构建目录或已安装副本也一样。只有用户提出要求时，才开始构建，以及依赖构建的测试和交付；绝不能为了完成更改而自行构建。构建请求涵盖与其一同提出的工作，除非用户将其设为长期指令，否则不会延续到之后的更改。在此之前，所有已构建或已安装的副本都落后于源代码；如果某项更改导致这种情况，要明确说明，并指出构建可以验证的内容仍属 unproven。测试针对的是已交付的技能，因此如果尚未记录交付路线，测试请求会先确定路线，然后构建、在此计算机上执行该路线并进行测试。仅重新构建受更改影响的目标，并保留检查失败和观察结果的记录。构建和完整性检查只能证明其所检查的属性；只有与当前源代码进行比对后，才能证明与源代码保持同步。缺失的行为或宿主证据属于 unproven。

在构建、运行 check、测试、声称已完成交付、说明证据覆盖范围之前，以及在采纳或发布决策时，请先打开 references/build-and-test.md。如果项目尚未记录交付路线，请在构建前打开 references/delivery.md；用户想要选择、更改或执行交付路线时，也请打开该文件。

仓库操作

已安装的技能包含一套封闭的创作 CLI。将 <skill-root> 设为包含此 SKILL.md 的目录；将工作目录设为包含源代码包的项目根目录（对于使用此技能创建的包，即包含 source/ 的文件夹）；然后运行 node "<skill-root>/scripts/skill-rails-cli/src/core/cli.mjs"，不带参数，或附带 help 或 --help，以获取当前版本的 inspect、overview、build 和 check 命令格式。无效的命令参数会返回包含特定任务 nextAction 的 JSON。对于用户针对整个包提出的问题，仅使用 overview 从该源代码包生成当前的非权威视图；不要将其另存为另一个事实来源。