specsfy-07-implement

实现任务并编写代码

必要准备

执行此技能前，必须先在项目根目录加载 $specsfy-setup。自动交接时，在此步骤前重新加载。复用对话中已确认的根目录；如果 setup 指出存在待处理事项，则不要继续。

交互模式

交互模式：perguntas。 提出任何问题前，请先阅读并遵循 .specsfy/Spec.md 中的 Contrato de perguntas numeradas。

按依赖顺序执行 spec.md 的 14. Tarefas 章节，并确保唯一信息源、测试、代码、证据和复选框彼此一致。

对于 Laravel，在添加或替换依赖前，请查阅 .specsfy/PACKAGES.md、docs/packages/README.md 和现有资料卡。如果任务提供 GitHub URL 或涉及 Composer 变更，请加载 $specsfy-specialist-laravel-package-manager，并在已安装的包满足要求时复用它们。

必须执行的数据库保护措施

执行任何测试、测试套件、回归测试或 migration 前，先运行：

node .agents/skills/specsfy-setup/scripts/check_database_safety.mjs \
  --project <raiz> --command "<comando-pretendido>"

在 Laravel 中，必须确保存在 .env.testing、APP_ENV=testing，并且数据库与 .env 中定义的开发数据库明确不同。状态为 PENDING 时，不得运行任何测试。修复环境后重新检查，只有状态为 SAFE 时才能继续。

忽略所有分类为 IGNORED 的命令。不得执行、转化为任务，也不得请求授权来运行 migrate:fresh、migrate:refresh、migrate:reset、migrate:rollback、db:wipe、schema:drop、prisma migrate reset、DROP DATABASE、DROP SCHEMA、DROP TABLE、TRUNCATE 或同等操作。同样不得运行间接脚本，以及使用 RefreshDatabase 或 DatabaseMigrations 的测试。使用事务隔离和最少量的 fixtures，不要清空数据库。

必须进行视觉审查

每项开发任务都必须进行视觉审查，即使用户没有提出要求。VISUAL 项位于 VERIFY 之后，并且必须在 EVIDENCE 之前完成。

对于任何涉及界面的变更，请阅读 DESIGNSYSTEM.MD、INTERFACE.md 和受影响的组件。在相关 viewport 和状态下检查渲染结果或 DOM。检查系统规范中的边框、间距、外边距、内边距和排版，以及对齐、宽度、溢出、焦点、缩放和文本换行。将检查方法、viewport、状态、调整和结果记录到任务中。

如果任务不涉及界面变更，请将 VISUAL 标记为 Não aplicável，并说明具体原因。即使用户没有要求视觉审查，也不得跳过此项。

协调对话

完成此步骤或发现属于其他步骤的工作时，宣布 Pendência detectada: <descrição> — ação: resolvendo nesta etapa，并在事项属于当前步骤范围时解决它。需要切换职责时，宣布 Transição automática: $specsfy-07-implement → $<destino> — motivo: <motivo> — resultado esperado: <resultado>，并立即加载目标技能，不要请求确认或重复命令。在同一对话中继续。完成当前步骤所需的修正后，宣布 Retomada automática: $<destino> → $specsfy-07-implement — pendência resolvida: <resultado>，并立即继续当前步骤。每次交接后重新评估状态，避免循环。交接无需请求确认；敏感操作仍需获得明确授权。

初始门槛

1. 根据 $specsfy-setup 中确认的路径解析根目录。如果用户提供了子目录，则将其视为项目，不要将其提升为 Git 根目录。读取 <raiz>/specs/planned/<NNNN>-<slug>/spec.md、research/ 中已索引的证据、仓库说明以及相关代码。不要查找 tasks.md、plan.md、research.md 或 data-model.md。
2. 要求满足 Formato: Specsfy/2.0、Status: Planned 或 Implementing、Definition Gate: Passed 和 Plan Gate: Passed。
3. 如果 Interface para pessoas 为 Sim，请阅读第 10 节，并确认计划中包含针对本地技术栈、页面、菜单和主导航、表单、操作、React 区块、shadcn/ui/ReUI 组件、状态以及交互测试的任务。在修改代码前，将当前技术栈、页面和流程与项目进行比较。保留记录范围之外的现有组件、路由、内容、权限和行为。如果缺少其中任何一项，或提议的技术未经确认就与现有技术不同，则自动返回 $specsfy-05-tasks；不要只将 CRUD 实现为 API 或持久化功能。 开始编程前，请确认第 10 节表格和 INTERFACE.md 中选择的项目；编程后，请使用所有新建、修改或复用的区块更新 INTERFACE.md。 对于 React 项目，必须在编写 JSX 或 TSX 前加载 $specsfy-specialist-react-ui-components。 如果尚未安装此 skill，请返回 $specsfy-setup，安装检测到的专家 skill，并在完成准备前不要实现页面。 对于 CRUD，还需确认所有页面复用同一个 PageHeader、DataGrid 占满宽度、ID 列始终可见、行链接指向详情页，以及行内的编辑和删除按钮彼此独立。
4. 针对 specs/<estado>/<NNNN>-<slug>/spec.md 执行验证器。如果此前已批准的计划因任务、TDD 前置任务或 RED 缺失而未通过某个门槛，请说明待处理事项，并自动返回 $specsfy-05-tasks；不要修改生产代码。该 skill 会重新开启第二幕、调用 TDD/BDD，并在计划重新验证通过后恢复本次实现。对于其他失败，请自动加载负责该门槛的 skill。
5. 使用 check_database_safety.mjs 检查基础测试套件的命令。仅在结果为 SAFE 后执行；如果没有独立的测试环境，则不要运行任何测试。记录已有失败，不要将其归因于新改动。
6. 在首次修改生产代码前，将 Status: Implementing 和 Delivery Gate: In Progress 设定好，并执行 specsfy transition <id> in-progress。
7. 使用以下内容选择已就绪的工作：

node .agents/skills/specsfy-07-implement/scripts/next_task.mjs \
  <raiz>/specs/<estado>/<NNNN>-<slug>/spec.md

如果没有已就绪的任务，请区分 concluído 和 bloqueado por dependência。

执行任务

1. 确认 ID、类型、引用、依赖项、文件和可验证结果；确认后立即标记为 PREP。
2. 对于 [TEST]，遵循 $specsfy-06-tdd-bdd：阅读 spec 中的 Gherkin 参考内容，并以此设计 TDD 测试；添加标记并确认 RED 有效。绝不创建或执行 .feature。在 PHP 中使用 Pest；在 Node 中仅使用用户确认的 runner。
3. 对于 [CODE]，确认前置 TDD 已完成，且覆盖相同的 ID，并在第 11 节记录 RED。否则停止，不要修改生产代码。宣布待办事项，并自动返回 $specsfy-05-tasks，以便重新打开计划、调用 $specsfy-06-tdd-bdd，并在新的 Plan Gate: Passed 后恢复此 skill。
4. 编写能使 TDD 测试通过的最小生产代码改动。对于界面任务，按照 spec 中定义的页面、菜单、表单和交互，以及所述状态进行实现；不要用 API 路由、空组件或缺少已约定页面的捷径替代流程。 在 React 中，遵循 $specsfy-specialist-react-ui-components，先定位、复用、调整并记录组件，再创建新的组合。 当任务使用 [MIGRATION] 时，先在计划路径创建带版本号的文件。通过 check_database_safety.mjs 检查命令，在测试数据库中应用 migration，并立即查询状态。在任务的 specsfy:evidence 注释中记录这两条命令及其零退出码。
5. 修改生产代码后、标记 EXECUTE 前，监控上下文：

node .agents/skills/specsfy-setup/scripts/monitor_context.mjs \
  --project <raiz> --check

对于待处理的技术栈，移交给 $specsfy-aux-stack；对于持久化，移交给 $specsfy-aux-database；对于已确认的规则，移交给 $specsfy-aux-rules。每次应用程序变更都要检查 PROJECT.md。如果对故事、用途、功能或边界没有实质影响，请在任务证据中记录评估，并使用 --acknowledge-project-no-change 重复检查。monitor 返回 PENDING 时，不要标记任务。 6. 每项 [CODE] 任务完成后，宣布 自动转换：$specsfy-07-implement → $specsfy-documentator — 原因：实现已更改系统 — 预期结果：docs/ 已重建并保持最新 并加载 $specsfy-documentator。根据所有现有代码重建文档，执行其 --check，仅在文档已更新后恢复此 skill。 7. 对于 [DOC] 或 [OPS]，提供所要求的特定证据。 8. 只有在交付内容和所需文档均存在于声明的路径中时，才标记 EXECUTE。 9. 使用 check_database_safety.mjs 重新检查每条测试命令。只有在状态为 SAFE 后，才能执行 TDD 焦点测试、相关测试套件和静态检查； 只有结果符合预期时，才标记 VERIFY。 10. 仅在所有检查均通过时进行重构。 11. 在第 11–13 节记录命令、结果和 ID，然后标记 EVIDENCE。如果存在 Evidence Contract: 1，还要在任务块中写入 JSON 注释 specsfy:evidence 并执行：

node .agents/skills/specsfy-07-implement/scripts/verify_evidence.mjs \
  specs/<estado>/<NNNN>-<slug>/spec.md . --task TNNN

完整执行产生 schema 2 认证时，使用 --attestation PATH 再次验证。要求 commit 兼容、绑定到同一 spec/任务、引用和命令完全一致、检查确实通过，并且每个文件的 SHA-256 均为当前值。--self-test 的认证不能证明交付已完成。 12. 进行简短回顾：应用发现的一项安全改进，或说明“无需改进”并给出理由；然后标记 IMPROVE。 13. 仅当六项均已完成（包括 VISUAL）时，才在 specs/<estado>/<NNNN>-<slug>/spec.md 的第 14 节将父项从 - [ ] 改为 - [x]。 14. 执行 validate_tasks.mjs，重新计算下一项任务，并检查 next_task.mjs 返回的下一项。 一项 [MIGRATION] 任务不能仅因为 model、query 或测试存在就视为完成。verify_evidence.mjs 要求提供迁移文件、应用迁移的命令，以及确认其状态的查询。缺少任何一项时，都要让 EXECUTE、VERIFY 和该任务保持未完成。

随着工作推进更新各项，不要等到收尾时再批量标记。只有在不涉及相同文件或状态时，才可以将 [P] 任务分组。如果执行过程中发现隐藏依赖，请在第 14 节中明确列出。

控制范围变更

如果实现需要未描述的行为、与某个 AC 矛盾，或会改变公共接口、数据、安全性或范围外内容，请停止。宣布待处理事项，并自动加载 $specsfy-update-spec。该 skill 会保留请求、判断是否需要进一步澄清需求方、更新规范来源、仅重新打开受影响的 gate，并重新执行验证、任务和 TDD/BDD。只有在各 gate 再次通过后，才恢复使用本 skill。按以下顺序更新：

specs/<estado>/<NNNN>-<slug>/spec.md (seções 1–13) → tarefas (seção 14) → testes → código → evidências na mesma spec

可逆的内部修正可以直接在代码中决定，并记录在报告中，无需重新打开规范。

完成 gate

第 14 节的所有任务均已标记后：

1. 运行完整的可用测试套件、lint、类型检查和 build；
2. 运行测试可追溯性检查；
3. 根据当前证据核对每一项 AC、FR、NFR 和 Definition of Done；
4. 查找未完成的任务、占位符、跳过的测试和已知故障；
5. 再次运行 monitor_context.mjs --project <raiz> --check，并解决所有待处理文档事项；
6. 加载 $specsfy-documentator，重建 docs/，并要求 build_documentation.mjs --project <raiz> --check 通过；
7. 如果缺少任何证据，不要宣布完成；
8. 对于每项 [MIGRATION] 任务，运行 verify_evidence.mjs，并确认迁移文件、应用情况和状态查询；
9. 只有在可追溯性完整时，才将 Delivery Gate 更改为 Passed，设置 Status: Reviewing，并运行 specsfy transition <id> review。$specsfy-04-validate 会完成验收并将 spec 移至 completed。

最终 gate 通过后，生成交付摘要预览，不要创建文件：

node .agents/skills/specsfy-07-implement/scripts/render_delivery.mjs \
  specs/<estado>/<NNNN>-<slug>/spec.md --format markdown

交付尚未完成时，请使用 --preview。将文本发布到 PR、commit 或外部工具中必须有明确请求；该脚本只向 stdout 写入内容。

阅读 references/completion-gates.md，了解如何完成收尾。

报告

报告已完成的任务、已更改的文件、命令及其结果、ID 覆盖情况、既有故障、下一项可开始的任务或最终 gate。最后，宣布并自动加载 $specsfy-progress，以检查根据规范来源派生的全局视图。发生故障时，宣布待处理事项，必要时自动加载负责的 skill，并让任务保持未完成，直到修复并恢复执行。

按需使用专家

执行本地上下文未涵盖其技术或风险的任务前，请阅读 references/specialists.md。 只有获得授权后，才能在使用方项目中安装。