SuperAPI AI Directory

arkweb-design-alignment

Coding & development

View repository

Updated 10-15 16:43

About this skill

Implement design alignment

Announce at start: "I am using the arkweb-design-alignment skill to perform implementation design alignment."

Execution Mode

Mode A: Subagent Mode

As an independent subagent, scheduled by arkweb-architect The main Session provides the design document path and code repository path, and the subagent performs difference comparison and requests decisions from the user one by one.

Mode B: Independent Invocation

When invoked directly by the user, the following must be provided:

  • Design document path (requirement.md + design.md)
  • Directory where the implementation code resides
  • Requirement analysis report path (optional)

If not provided, the skill will automatically search for documents under {DOCS_REPO}/docs/features/{feature-name}/ .

Input

Input Item Path Required Description
requirement.md {docs_dir}{feature-name}/{date}-{feature}-requirement.md Yes Requirement baseline review document
design.md {docs_dir}{feature-name}/{date}-{feature}-design.md Yes Architecture design document
spec.md {docs_dir}{feature-name}/spec.md No Unified specification document (supplementary reference)
analysis.md {analysis_dir}{date}-{feature}-analysis.md No Code analysis report
Implementation code directory {WORK_HOME}/ Yes Code repository root path

Execution Steps

Step 1: Collect information from three parties and identify differences

Read all input documents in parallel and extract all information needed for comparison:

1. Read requirement.md + design.md
   → 提取:接口定义、API 签名、数据结构、流程描述、约束条件

2. Read spec.md(如存在)
   → 提取:结构化接口规格、参数约束、行为场景

3. Read analysis.md(如存在)
   → 提取:实现步骤清单、代码探查结果

4. 在代码仓库中搜索实现代码
   → 使用 Grep + Read 查找头文件和实现文件
   → 提取实际的类定义、方法签名、数据结构

Comparison Dimension:

Design Element Comparison Method Difference Type
Interface/API Signature API definitions in the design document vs header files in the actual code Signature difference
Data structure/enum Field definitions in the design document vs actual struct/enum Field difference
Class/inheritance relationship Class diagram in the design document vs actual class definitions Structural difference
Method list Method list in the design document vs actual method list Addition/removal difference
Parameters/return values Parameter descriptions in the design document vs actual parameter types Type difference
Process/state machine Flowcharts in the design document vs actual control flow Logic difference
Error codes/exceptions Error definitions in the design document vs actual error handling Exception difference
Feature Flag Switch planning in the design document vs actual flag definitions Configuration difference
Multi-language binding scope Binding requirements in the design document vs actual binding coverage Scope difference
Module division Module boundaries in the design document vs actual file organization Architecture difference

Execution method: For each interface/class/method described in the design document, use Grep + Read to find the corresponding implementation in the actual code and compare item by item.

Collect all differences into a list, preparing to enter the user decision step.

Step 2: Show differences to the user one by one and request decisions

For each difference point, use the AskUserQuestion tool to present it to the user and request a decision.Show only one difference point at a time, and wait for the user's explicit reply before handling the next one.

Display format:

差异 {N}/{Total}: {差异标题}

设计文档描述:
  {设计文档中的原始描述,包含章节引用}

实际实现:
  {代码中实际的实现情况}

差异分析:
  {简要说明差异的原因和影响}

请选择处理方式:
  A) 接受实现 — 将设计文档修改为与实现一致(回写设计文档)
  B) 要求重做 — 按设计文档的要求重新实现代码(启动 coder+reviewer)
  C) 暂时搁置 — 记录为遗留事项,后续处理

Explanation of user decision options:

Option Meaning Follow-up action
A) Accept implementation The implementation is reasonable, and the design document needs to be updated Directly Edit the original section of the design document
B) Request rework The implementation deviates from the design intent, and the code needs to be corrected Start the coder → reviewer loop
C) Temporarily shelve Cannot decide immediately, handle later Record in the pending items list

Step 3: Handle by category according to user decisions

Collect user decisions for all difference points and group them by handling method:

决策 A(接受实现)的差异数量: {a_count}
决策 B(要求重做)的差异数量: {b_count}
决策 C(暂时搁置)的差异数量: {c_count}

Step 4: Execute user decisions

For differences with decision A (accept implementation): directly write back to the design document

Key principle: directly modify the original section of the design document, rather than appending an explanation at the end.

For each difference with decision A:

  1. Use Read to locate the corresponding original section in the design document
  2. Use Edit modify in placethe original description so that it is consistent with the actual implementation
  3. Do not append a summary section at the end, and only annotate the source of modification at the modified location

Modification principles:

  • Only modify paragraphs/sections that are inconsistent with the implementation, without changing the overall document structure
  • Maintain the writing style and terminology of the original document
  • Use Edit for precise replacement, not overwriting the entire document
  • Annotate the source and reason of each change via inline comments

For differences with decision B (request rework): start the coder+reviewer rework loop

Integrate all decision B differences into rework requirements and pass them to the arkweb-coder Agent:

请根据以下用户决策,重新实现代码以对齐设计文档。

需求设计文档路径:{requirement_path}
设计文档路径:{design_path}

用户要求重做的差异点:

差异 1: {差异标题}
  设计文档要求:{设计文档的原始描述}
  当前实现:{当前代码的实现}
  需要修改为:{与设计文档一致}

差异 2: ...

请按以下步骤执行:
1. 读取需求设计文档中对应的章节
2. 使用 TodoWrite 创建修复任务列表
3. 逐个修改代码文件以对齐设计文档
4. 修改完成后输出变更文件清单

After rework is complete, start the arkweb-reviewer Agent to review only the files involved in the rework.

If the review still has BLOCKER/CRITICAL issues, continue the fix loop (up to 3 rounds).

For differences with decision C (temporarily shelve): record them as pending items

Do not modify the design document, and do not modify the code. Only list them in the final summary.

Step 5: Difference alignment loop check

如果有决策 B 的差异触发了重做:
    → 重新执行 Step 1(重新收集信息并比对)
    → 检查重做是否引入了新的差异
    → 如果有新差异 → 回到 Step 2(向用户展示新差异)
    → 如果无新差异 → 退出循环

如果无决策 B 的差异:
    → 直接退出循环,所有差异已处理完毕

Loop protection:

max_diff_rounds = 5
如果差异对齐循环超过 5 轮:
    → 向用户报告仍有未对齐的差异
    → 列出剩余差异
    → 建议人工介入

Step 6: Output difference handling summary

After completing the handling of all differences, output a summary to the user:

═══════════════════════════════════════════
  设计差异对齐完成
═══════════════════════════════════════════
需求文档: {requirement_path}
设计文档: {design_path}

差异统计:
  总差异点: {N}

用户决策分布:
  接受实现(已回写设计文档): {A_count} 处
  要求重做(已重新实现):     {B_count} 处
  暂时搁置(记录为遗留):     {C_count} 处

已直接修改的设计文档章节:
  - {章节1} ({差异标题}): {修改摘要}
  - {章节2} ({差异标题}): {修改摘要}

已重新实现的代码文件:
  - {文件1}: {修改说明}
  - {文件2}: {修改说明}

遗留事项(用户选择搁置):
  - [ ] {差异标题}: {设计要求 vs 实际实现}
═══════════════════════════════════════════

Process status tracking

Use TodoWrite to maintain progress:

Step 1: 收集信息并识别差异    [pending / in_progress / completed]
Step 2: 向用户展示差异并决策  [pending / in_progress / completed]
Step 3: 分类处理              [pending / in_progress / completed]
Step 4: 执行用户决策          [pending / in_progress / completed]
Step 5: 差异对齐循环检查      [pending / in_progress / completed]
Step 6: 输出总结              [pending / in_progress / completed]
  └─ 差异决策轮次 (1~5)       [追踪当前是第几轮差异对齐]

Exception handling

No differences

  • Report to the user that "the design document is fully consistent with the implementation, no alignment needed"
  • Exit directly

Maximum rounds reached but differences remain

  • Stop the difference alignment loop
  • Report to the user that there are still unaligned differences
  • List the remaining differences and suggested handling methods
  • Preserve the results of completed difference handling

Design document does not exist

  • Report the path error to the user
  • Indicate the correct document path

No implementation found in the code repository

  • Report to the user that the corresponding implementation code was not found
  • List the interfaces/classes defined in the design document but not implemented
  • Suggest completing the code implementation first