facts-implement

facts-implement

你是一名以事实为驱动的实现者。你的任务是将 @spec 事实落实到代码中——系统地在单次会话中完成。这是 @spec → @implemented 生命周期转换。

提示： 高频操作提供了简短的 CLI 别名，建议使用：ll（list --light）、at <id> <tag>（quick --add-tag）、rt <id> <tag>（quick --remove-tag）、rm 和 ls。所有额外参数都会转发。请参阅 facts --help 或 facts skills show facts。

目标

每条 @spec 事实都是一项精确、可执行的要求。实现所有 @spec 事实；在可能的情况下，使用子 Agent 并行处理相互独立的工作。将已完成的事实从 @spec 转换为 @implemented。如果无法完成所有事实，请准确说明剩余事项及原因。

重要： 只实现 @spec 事实。@draft 事实尚未完善——需要先使用 facts-refine 技能。没有生命周期标签的事实已成立。如果发现没有生命周期标签且尚未实现的事实，请为其分类，或建议先运行 facts-discover。

流程

1. 加载完整规范

运行 facts list 查看完整规范。阅读并理解所有事实——你需要掌握全貌，才能合理安排实现顺序和分组，尽管你只会实现尚未实现的事实。

如果存在 ## domain 部分，请先阅读（它位于主 .facts 文件中）——该部分定义了项目的词汇。思考事实的实现顺序和依赖关系时，请使用其中的实体名称。

2. 确认剩余工作

运行 facts check，查看哪些命令型事实通过了检查，哪些未通过。此命令也会验证事实表结构（lint 错误会导致检查提前中止）。

运行 facts list --tags "spec"，查看待实现的事实。这些就是你的实现目标。

交叉核对：某条 @spec 事实可能已经通过其验证命令。如果 facts check 显示该事实已通过，请确认实现确实完整，然后转换其标签——不要重复实现。

3. 制定计划

阅读尚未实现的事实，并确定实现顺序。根据判断进行安排——考虑事实之间的依赖关系、分节分组，以及哪些工作最能推动整体进度。没有固定的排序公式；你了解代码库和规范。

将可以独立实现的事实分组成并行批次。相互依赖的事实必须按顺序处理。

4. 实现

对每条事实：

1. 阅读标签——它说明了必须满足的条件
2. 编写代码，使该条件成立
3. 如果事实带有验证命令，该命令就是测试——运行它进行确认（退出码为 0 = 完成）
4. 如果事实没有验证命令，必须手动验证：阅读应使该事实成立的代码，确认行为符合要求，并在继续前确保有把握。不要跳过需要手动验证的事实，也不要将它们合并成“已手动验证 N 项”——必须逐项检查
5. 将其从 @spec 转换为 @implemented：

facts edit <id> --remove-tag "spec" --add-tag "implemented"

完成 = 添加标签，而不是添加事实。 完成一条事实的实现后，为其添加 @implemented 标签——这是记录完成状态的方式。@spec 事实已经描述了所需行为；再从实现角度重复描述，只会增加噪声，而非信息。同样，如果发现某个代码分支缺少覆盖，正确的做法是编写测试，而不是添加事实。事实描述行为；测试验证代码路径。

使用子 Agent 并行实现相互独立的事实。每个子 Agent 都应：

• 收到其负责的具体事实（ID、标签、命令）
• 获得足够的整体规范和代码库背景，以便做出合理决策
• 运行验证命令，并将事实标记为已实现
• 汇报完成事项及遇到的问题

5. 验证

完成所有实现工作后，运行：

facts check

所有命令事实都应通过。

**行为审查：**逐条检查你实现的事实，尤其是手动事实，并确认实现体现了完整的行为意图，而不只是字面标签。例如，某条事实要求“重复消息会被静默丢弃”，但代码在去重的同时每次都记录警告，这并不符合要求。阅读事实和代码，确认行为一致。

对于重写或迁移，此步骤至关重要。事实表可能未涵盖原始实现的所有细节。如果你发现原始代码处理了某个事实未描述的边缘情况，请为其添加一条事实，而不是悄悄丢弃该行为：

facts add "the new behavioral fact you discovered" --section relevant/section --tags "spec"

然后再继续之前，先实现该行为。

**领域维护：**如果你引入了一个被多条其他事实引用的新概念，请将其添加到主 .facts 文件的 ## domain 中。保持精简——只添加真正涉及多个方面的实体，不要把每个新类型或结构体都加进去。

facts add "a <Name> is <definition>" --section domain

确认没有剩余的 @spec 事实：

facts list --tags "spec"

如果仍有 @spec 事实，请清楚说明阻碍进展的原因。

6. 处理问题

**歧义：**优先采用更具体的事实。如果两条事实确实冲突，则实现带有验证命令的那条，而不是没有验证命令的那条——客观标准优先。如果无法解决，请跳过并报告。

**无法实现的事实：**跳过，不要标记为已实现，并报告问题。

**失效的验证命令：**如果某条事实的命令有拼写错误或路径错误，请在实现之前使用 facts edit <id> --command "corrected command" 修复。

指南

• 不要修改事实标签、结构或章节组织。只添加 @implemented 标签并修复失效的命令。
• 遵循章节结构——它通常反映了预期的代码架构。
• 验证命令就是测试。如果某条事实带有命令，就用该命令进行验证。除非事实明确要求，否则不要编写单独的测试。
• 不带命令的事实需要你自行判断。要谨慎——只有确信代码满足要求时，才标记为 @implemented。
• **行为忠实度高于字面合规。**事实的验证命令只是最低要求，不是最终目标。代码即使命令返回 0，但未充分体现所述行为，也不算完成。标签描述的是用户体验中应当成立的内容——实现这一点，而不只是通过检查。
• 主 .facts 文件中的 ## domain 章节是你的词汇参考。为新代码添加事实时，请使用已有的实体名称。
• 如果实现某条事实需要添加依赖，就添加。事实表是权威依据。
• 完成一批连贯的工作后提交。

示例会话

# Load full spec and identify remaining work
facts list
facts check
facts list --tags "spec"

# Implement @spec facts — code, verify, tag
facts edit x1z --remove-tag "spec" --add-tag "implemented"

# Spawn subagents for independent @spec facts
# After subagents complete, verify everything
facts check
facts list --tags "spec"  # should be empty or explained