bb-rtl-coder

资深RTL设计工程师，根据微架构文档（MAS、FSM、datapath）编写可综合的 SystemVerilog HDL代码。Generate synthesizable SystemVerilog RTL from MAS documents. Trigger: /bb-rtl-coder, RTL实现, SystemVerilog代码, 可综合HDL

SKILL.md

GitHub
<DEFAULTS> output_dir: ./rtl language: sv auto_approve: false project_dir: auto-detect module_id: all parallel: 4 dry_run: false resume: false full: false synthesis_tool: generic </DEFAULTS>

Pipeline Position

spec_mas/ ──→ [bb-rtl-coder] ──→ rtl/ ──→ bb-code-review ──→ synthesis
      INPUT_DIR          OUTPUT_DIR        AUTO

HARD-GATE 定义

<HARD-GATE>
在任何 RTL 生成操作前，必须完成以下步骤：

1. 定位 INPUT_DIR + 验证必需文档（MANDATORY）
   - 若用户提供路径，验证存在
   - 否则自动检测最新子目录
   - 每个模块必须有 MAS.md（至少有接口定义）
   - 叶子模块必须有 FSM.md 和 datapath.md

2. 创建工作目录（MANDATORY）
   ```bash
   mkdir -p {{ OUTPUT_DIR }}
   mkdir -p {{ CHECKPOINT_DIR }}
   mkdir -p {{ PROGRESS_DIR }}
  1. 运行 Change Detection（MANDATORY） → 决定 full run 或 incremental run

禁止行为（在完成初始化前）：

  • 加载 spec_mas 输入
  • 启动 RTL 模块树生成
  • 输出 RTL 文件</HARD-GATE>

---

## 铁律（违反即停止）

> 以下规则不受 auto_approve 影响，任何模式下均不得绕过。

| 铁律 | 检查点 | 失败动作 |
|------|--------|----------|
| **Spec 先行铁律** | MAS 文件 < 2 份 | 拒绝执行，返回 bb-mas 阶段 |
| **叶子优先铁律** | 子模块 RTL 未完成 | 禁止开始父模块 RTL |
| **可综合性铁律** | RTL 有不可综合构造 | 立即修复，不继续 |
| **端口一致铁律** | 端口 ≠ MAS.md §2.1 | 立即修复，不继续 |
| **状态机编码铁律** | FSM 状态编码 ≠ FSM.md | 立即修复，不继续 |
| **并行上限铁律** | 子 agent > 6 | 拆分批次执行 |

---

## Global Paths

PROJECT_DIR = {{ project_dir 参数 或 auto-detect }} INPUT_DIR = {{ PROJECT_DIR }}/spec_mas OUTPUT_DIR = {{ PROJECT_DIR }}/rtl TEMPLATE_DIR = ~/.claude/skills/bb-rtl-coder/templates REFERENCE_DIR = ~/.claude/skills/bb-rtl-coder/references SCRIPT_DIR = ~/.claude/skills/bb-rtl-coder/scripts PROJECT_SCRIPTS = {{ PROJECT_DIR }}/scripts PROGRESS_DIR = {{ OUTPUT_DIR }}/.progress CHECKPOINT_DIR = {{ OUTPUT_DIR }}/.checkpoint SKILL_FILE = ~/.claude/skills/bb-rtl-coder/SKILL.md EVOLUTION_FRAMEWORK = ~/.claude/evolution-framework


---

## 增量更新机制

当 `/bb-mas` 重新生成或更新 `spec_mas/` 后再次执行 `/bb-rtl-coder`，自动检测变更并仅更新受影响模块。

### Spec Snapshot

每次成功执行后，将所有 spec 文件的哈希存入 `${CHECKPOINT_DIR}/spec_snapshot.json`：

```json
{
  "snapshot_time": "2026-05-16T12:00:00+08:00",
  "files": {
    "module_tree.md": "<sha256>",
    "M01/MAS.md": "<sha256>",
    "M01/FSM.md": "<sha256>",
    "M01/datapath.md": "<sha256>",
    "M02/MAS.md": "<sha256>"
  }
}

Change Detection

在 Prerequisites 段自动执行：

IF spec_snapshot.json 不存在 → FULL RUN（首次执行）
IF spec_snapshot.json 存在 → 逐文件比较哈希：
  ├─ module_tree.md 变更 → 解析新增/删除/重组的模块
  ├─ M*/MAS.md 变更       → 标记该模块为 modified
  ├─ M*/FSM.md 变更       → 标记该模块为 modified
  ├─ M*/datapath.md 变更  → 标记该模块为 modified
  └─ 全部文件哈希一致    → SKIP（输出 "No spec changes detected"）

Impact Classification

分类 触发条件 处理方式
added module_tree.md 中新增的模块 完整 RTL 生成流程
removed module_tree.md 中删除的模块 归档 RTL 到 temp/deleted/
modified MAS/FSM/datapath 哈希变更 完整 RTL 重写
cascade 依赖 modified 模块的父模块 重新检查端口连接
unchanged 无变更且不依赖变更模块 跳过

规模感知执行模式

在读取 module_tree.md 后，统计总模块数并选择编排模式：

# 读取 SessionStart hook 预生成的上下文预算
cat ~/.claude/ctx_budget.env 2>/dev/null || echo "SAFE_TOKENS=100000"

SAFE_TOKENS=$(grep SAFE_TOKENS ~/.claude/ctx_budget.env | cut -d= -f2)
TOTAL_MODULES=$(grep -c "^- M" "${INPUT_DIR}/module_tree.md" 2>/dev/null || echo 0)

INLINE_MODULE_MAX=$(python3 -c "t=$SAFE_TOKENS; print(min(t//1000,30))")
BATCHED_MODULE_MAX=$(python3 -c "t=$SAFE_TOKENS; print(min(t//300,80))")

if   [ "$TOTAL_MODULES" -le "$INLINE_MODULE_MAX" ];  then MODE="inline"
elif [ "$TOTAL_MODULES" -le "$BATCHED_MODULE_MAX" ];  then MODE="batched"
else                                                        MODE="delegated"
fi

echo "Modules: $TOTAL_MODULES  inline≤$INLINE_MODULE_MAX  batched≤$BATCHED_MODULE_MAX → MODE=$MODE"
模式 适用规模 Orchestrator context 策略
inline ≤ 30 模块 所有模块追踪在当前 context
batched 30 < modules ≤ 80 每批完成后 /compact，状态依赖 checkpoint
delegated > 80 模块 每层派发 subagent，主 context 只追踪层级进度

Context Budget 控制

  • 每完成一个批次（4-8 模块）→ 执行 /compact
  • /compact 前确保进度已写入 ${CHECKPOINT_DIR}/*.done
  • /compact 后从 checkpoint 文件恢复状态继续

Execution Flow（MANDATORY）

全程自动执行，无需用户确认。 从叶子模块到父模块 + 综合检查 + 自动 impl-review + Fix Issues + Push。

Phase 1–4: RTL Generation（叶子→父） → Phase 5: Synthesis Check
      │
      ↓
Phase 6: Auto code-review（自动调用 bb-code-review）
      │ → 输出: ${OUTPUT_DIR}/.review/issues.md
      │
      ↓
Phase 7: Fix Issues（自动修复所有 CRITICAL/HIGH）
      │ → 修复 → 重检 → 迭代（最多 3 轮）
      │
      ↓
Phase 8: Push to Remote
      │
      ↓
Final Report 输出

Phase 1：构建 RTL 模块树

1.1 输入规模检测

MAS_COUNT=$(find ${INPUT_DIR} -name "MAS.md" | wc -l)
FSM_COUNT=$(find ${INPUT_DIR} -name "FSM.md" | wc -l)

if [ "$MAS_COUNT" -lt 2 ]; then
    echo "ERROR: MAS 文件不足 2 份，返回 bb-mas 阶段"
    exit 1
fi

1.2 解析模块树

从 spec_mas/module_tree.md 读取模块层级结构：

M01_ALU/
├── M01a_IntegerALU/
│   └── M01a1_Adder/
│   └── M01a1_Multiplier/
├── M01b_FloatALU/

1.3 创建 RTL 目录结构

mkdir -p {{ OUTPUT_DIR }}/M01_ALU/src
mkdir -p {{ OUTPUT_DIR }}/M01_ALU/tb
mkdir -p {{ OUTPUT_DIR }}/M01a_IntegerALU/src
mkdir -p {{ OUTPUT_DIR }}/M01a_IntegerALU/tb

1.4 输出 RTL 模块树文档

写入 {{ OUTPUT_DIR }}/rtl_tree.md

Phase 2：叶子模块 RTL 编写（并行）

子 agent 指令模板

## 任务：编写叶子模块 RTL

**路径规范**：
- 输入目录：{{ INPUT_DIR }}/{{ MODULE_PATH }}
- 输出文件：{{ OUTPUT_DIR }}/{{ MODULE_PATH }}/src/{{ MODULE_NAME }}.sv
- 参考文档：{{ REFERENCE_DIR }}/sv_coding_style.md

**输入文件**：
1. MAS.md — 接口定义、时序规格
2. FSM.md — 状态机定义
3. datapath.md — 数据通路结构
4. regmap.md — 寄存器映射定义（可选，有寄存器接口的模块必须提供）

**Traceability 注入规则**：

**A. Spec Header（模块级摘要）**：

每个 RTL 文件头部必须包含 Spec Header，为 AI agent 和人工 reviewer 提供快速上下文：

```systemverilog
//==============================================================================
// Module: {{ MODULE_NAME }}
// 
// SPEC HEADER
// ─────────────────────────────────────────────────────────────────────────────
// Source:       spec/MAS/{{ MODULE_ID }}_{{ MODULE_NAME }}/MAS.md
// Version:      {{ SPEC_VERSION }}
// Status:       {{ DRAFT|REVIEW|FROZEN }}
// Spec Hash:    {{ sha256:xxxxxxxxxxxx }}  ← 由 scripts/compute_spec_hash.py 计算
// REQ Coverage: REQ-{{ MODULE_ID }}-F01 ~ REQ-{{ MODULE_ID }}-F{{ MAX_F }}
// 
// Purpose:
//   {{ 一行描述模块功能 }}
// 
// Key Constraints:
//   [C1] {{ 关键约束 1，如：最大同时调度线程数: 2 }}
//   [C2] {{ 关键约束 2，如：op_valid → op_ready 响应时间: 1-5 cycles }}
//   [C3] {{ 关键约束 3，如：复位后 syst_mode = 0 }}
// 
// Dependencies:
//   - {{ 依赖模块 1，如：M02_SRAM (存储接口) }}
//   - {{ 依赖模块 2，如：M06_ClockManager (时钟源) }}
// 
// Traceability:
//   PRD:  spec/PRD/PRD.md §{{ SECTION }}
//   ARCH: spec/ARCH/{{ FILE }}.md §{{ SECTION }}
//   MAS:  spec/MAS/{{ MODULE_ID }}_{{ MODULE_NAME }}/MAS.md
//   REGMAP: spec/MAS/{{ MODULE_ID }}_{{ MODULE_NAME }}/regmap.md  ← 若有寄存器定义
// 
// Change Log:
//   {{ VERSION }} - {{ DATE }}: {{ CHANGE_DESCRIPTION }}
//==============================================================================

B. REQ_ID 标注：

  1. 从 MAS.md §10 提取 REQ_ID 列表（REQ-M##-F## 格式）
  2. 模块声明前添加：// @requirement REQ-M##-F01, REQ-M##-F02 @auto:rtl-gen
  3. 选择性内联（避免过度标注）：
代码块类型 必须标注 示例
Module 声明 ✅ module M01_DataflowController
FSM (always_ff with case) ✅ 状态机实现
协议握手逻辑 ✅ handshake, AXI, APB
关键计算路径 ✅ datapath, pipeline stages
寄存器阵列 ✅ reg_file, context storage
简单赋值 (assign) ❌ assign valid = en && ready;
端口声明 ❌ input logic clk;
参数定义 ❌ parameter WIDTH = 32;
  1. SVA 断言必须包含 @verifies + @spec_ref + @constraint 注释：
// @verifies REQ-M##-F04
// @spec_ref MAS/{{ MODULE_ID }}/datapath.md §{{ SECTION }}
// @constraint {{ 自然语言约束说明 }}
property p_xxx;
    ...
endproperty
assert property (p_xxx)
    else $error("[SPEC §x.x] {{ 失败描述 }}");

SVA 生成规则：

  1. 从 verification.md §3 断言列表读取断言规格（ID、条件、严重性）
  2. 将每条断言转换为 SystemVerilog concurrent assertion
  3. 每个 SVA 前添加 @verifies REQ-M##-F## 和 @requirement REQ-M##-F##
  4. 断言失败时使用 $error 输出断言 ID 和描述

示例：

//==============================================================================
// Module: M01_DataflowController
// 
// SPEC HEADER
// ─────────────────────────────────────────────────────────────────────────────
// Source:       spec/MAS/M01_DataflowController/MAS.md
// Version:      1.2
// Status:       FROZEN
// Spec Hash:    sha256:abc123def456
// REQ Coverage: REQ-M01-F01 ~ REQ-M01-F12
// 
// Purpose:
//   NPU 数据流控制器，协调 systolic array 的运算调度。
// 
// Key Constraints:
//   [C1] 最大同时调度线程数: 2
//   [C2] op_valid → op_ready 响应时间: 1-5 cycles
//   [C3] 复位后 syst_mode = 0 (inference mode)
// 
// Dependencies:
//   - M02_SRAM (存储接口)
//   - M06_ClockManager (时钟源)
// 
// Traceability:
//   PRD:  spec/PRD/PRD.md §3.1
//   ARCH: spec/ARCH/block_diagram.md §2
//   MAS:  spec/MAS/M01_DataflowController/MAS.md
//==============================================================================

// @requirement REQ-M01-F01, REQ-M01-F02 @auto:rtl-gen
module M01_DataflowController (
    input  logic clk,
    input  logic rst_n,
    ...
);

    // @requirement REQ-M01-F03
    always_ff @(posedge clk or negedge rst_n) begin
        ...
    end

    // @verifies REQ-M01-F04
    // @spec_ref MAS/M01/datapath.md §3.2
    // @constraint 握手协议: valid 拉高后，ready 必须在 1-5 个周期内响应
    property p_handshake;
        @(posedge clk) disable iff (!rst_n)
        valid |-> ##[1:5] ready;
    endproperty
    p_handshake_check: assert property (p_handshake)
        else $error("[SPEC §3.2] Handshake protocol violation: valid without ready");

    // @verifies REQ-M01-F05
    // @spec_ref MAS/M01/datapath.md §3.3
    // @constraint FIFO 不溢出: full 时禁止写入
    property p_fifo_no_overflow;
        @(posedge clk) disable iff (!rst_n)
        (fifo_full && wr_en) |-> ##0 1'b0;
    endproperty
    p_fifo_no_overflow_check: assert property (p_fifo_no_overflow)
        else $error("[SPEC §3.3] FIFO overflow: write when full");

endmodule

RTL 质量要求：

  1. 端口定义：与 MAS.md §2.1 完全一致
  2. 状态机：与 FSM.md 状态编码一致
  3. 数据通路：实现 datapath.md 流水线结构
  4. 可综合性：无 initial 块（除 testbench）、无 delay、无递归
  5. 时钟域：单一时钟域；CDC 模块需标注
  6. Traceability：每个功能块必须有 @requirement 注释

禁止事项：

  • 禁止使用 initial（testbench除外）
  • 禁止使用 #delay
  • 禁止使用 force/release
  • 禁止使用递归模块实例化
  • 禁止使用 wait 语句
  • 禁止省略 @requirement 注释

寄存器接口生成（当模块有 regmap.md 时）：

  1. 从 regmap.md §1 读取寄存器列表，实现 APB 寄存器读写逻辑：

    • RW 寄存器：写更新、读返回当前值
    • RO 寄存器：写忽略、读返回硬件状态
    • W1C 寄存器：写 1 清零对应位
    • RESERVED 位：写入忽略

  2. 生成寄存器文档和 SVA 断言：

    uv run $PROJECT_SCRIPTS/generate_regmap_doc.py \
    --regmap spec/MAS/{{ MODULE_ID }}/regmap.md \
    --output doc/regmap/

uv run $PROJECT_SCRIPTS/generate_regmap_assertions.py \
    --regmap spec/MAS/{{ MODULE_ID }}/regmap.md \
    --output {{ OUTPUT_DIR }}/{{ MODULE_PATH }}/src/{{ MODULE_NAME }}_regmap_assertions.sv

  3. 在 RTL 中 bind 生成的断言模块：

    // 在 {{ MODULE_NAME }}.sv 末尾
`ifdef FORMAL
bind {{ MODULE_NAME }} {{ MODULE_NAME }}_regmap_assertions u_regmap_assertions (
    .clk(clk), .rst_n(rst_n),
    .addr(paddr), .sel(psel), .enable(penable),
    .write(pwrite), .wdata(pwdata), .rdata(prdata)
);
`endif


### 叶子模块 RTL 结构

```systemverilog
// {{ MODULE_NAME }}.sv
// Generated by rtl-coder from spec_mas/{{ MODULE_PATH }}

module {{ MODULE_NAME }} (
    // Clock & Reset
    input  logic        clk,
    input  logic        rst_n,
    
    // Input Ports (from MAS.md §2.1)
    input  logic [WIDTH-1:0]  {{ port_name }},
    ...
    
    // Output Ports (from MAS.md §2.1)
    output logic [WIDTH-1:0]  {{ port_name }},
    ...
);

    // FSM States (from FSM.md)
    typedef enum logic [N-1:0] {
        IDLE    = {{ encoding }},
        ACTIVE  = {{ encoding }},
        ...
    } state_t;
    
    state_t current_state, next_state;
    
    // Datapath Registers (from datapath.md)
    logic [WIDTH-1:0] {{ reg_name }};
    ...
    
    // FSM Sequential Logic
    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            current_state <= IDLE;
            {{ reset_values }}
        end else begin
            current_state <= next_state;
            {{ sequential_updates }}
        end
    end
    
    // FSM Combinational Logic
    always_comb begin
        next_state = current_state;
        {{ default_outputs }}
        
        case (current_state)
            IDLE: begin
                if ({{ condition }}) begin
                    next_state = ACTIVE;
                    {{ state_outputs }}
                end
            end
            ...
        endcase
    end
    
    // Datapath Logic (from datapath.md)
    {{ datapath_logic }}
    
endmodule

Phase 3：父模块 RTL 编写（逐层上卷）

从最深的父模块开始，逐层向上编写。

父模块 RTL 特殊内容

module {{ PARENT_MODULE }} (
    // Top-level Ports (from MAS.md)
    ...
);

    // Sub-module Instantiations
    {{ SUB_MODULE_1 }} u_{{ SUB_MODULE_1 }} (
        .clk   (clk),
        .rst_n (rst_n),
        {{ port_connections }}
    );
    
    {{ SUB_MODULE_2 }} u_{{ SUB_MODULE_2 }} (
        ...
    );
    
    // Inter-module Connections
    logic [WIDTH-1:0] {{ interconnect_signal }};
    
    // Top-level FSM Coordination (if applicable)
    {{ top_fsm }}
    
endmodule

端口连接原则

  • 子模块输出 → 父模块内部信号
  • 子模块输入 → 父模块内部信号或顶层端口
  • 端口位宽必须匹配

Phase 4：Testbench 生成

Testbench 结构

// tb_{{ MODULE_NAME }}.sv
// Testbench for {{ MODULE_NAME }}

`timescale 1ns/1ps

module tb_{{ MODULE_NAME }};
    
    // Clock & Reset Generation
    logic clk;
    logic rst_n;
    
    initial begin
        clk = 0;
        forever #{{ CLOCK_PERIOD }} clk = ~clk;
    end
    
    initial begin
        rst_n = 0;
        #{{ RESET_PERIOD }};
        rst_n = 1;
    end
    
    // DUT Instance
    {{ MODULE_NAME }} dut (
        .clk   (clk),
        .rst_n (rst_n),
        {{ port_connections }}
    );
    
    // Test Sequences (from verification.md)
    initial begin
        {{ test_sequence_1 }}
        {{ test_sequence_2 }}
        ...
        $finish;
    end
    
    // Assertions (from verification.md)
    {{ assertions }}
    
    // Waveform Dump
    initial begin
        $dumpfile("{{ MODULE_NAME }}.vcd");
        $dumpvars(0, tb_{{ MODULE_NAME }});
    end
    
endmodule

Phase 5：综合性检查（MANDATORY）

5.1 可综合性规则检查

python3 {{ SCRIPT_DIR }}/synthesis_check.py \
    --input {{ OUTPUT_DIR }}/{{ MODULE_PATH }}/src \
    --report {{ OUTPUT_DIR }}/{{ MODULE_PATH }}/syn_check.json
规则 描述 严重性
NO_INITIAL 禁止 initial 块（TB除外） CRITICAL
NO_DELAY 禁止 #delay 语句 CRITICAL
NO_FORCE 禁止 force/release CRITICAL
NO_WAIT 禁止 wait 语句 CRITICAL
NO_RECURSION 禁止递归实例化 CRITICAL
NO_LATCH 禁止锁存器生成 HIGH
SINGLE_CLOCK 单时钟域检查 HIGH
PORT_WIDTH 端口位宽一致性 HIGH
FSM_ENCODING FSM 状态编码一致性 HIGH

5.2 Gap Analysis（类似 Coverage Gap Analysis）

若检查发现问题，必须执行以下步骤：

  1. 识别问题位置

    python3 -c "import json; r=json.load(open('syn_check.json')); print([i for i in r['issues'] if i['severity']=='CRITICAL'])"

  2. 问题分类处理

    类型 处理方式
    不可综合构造 立即删除/替换
    锁存器生成 添加默认值/完整分支
    端口不匹配 调整位宽/添加显式转换
    状态编码错误 复制 FSM.md 编码

  3. 修复验证循环

    • 修复 → 重检 → 直到无 CRITICAL/HIGH

禁止行为：

  • ❌ 跳过问题分析
  • ❌ 声称"只有一个 latch 问题不大"
  • ❌ 在有 CRITICAL问题时继续下一阶段

Phase 6：自动 impl-review（MANDATORY AUTO）

自动执行，无需用户确认。 调用 bb-code-review 进行对抗性评审：

Skill(skill="bb-code-review", args="--spec_path ${INPUT_DIR} --code_dir ${OUTPUT_DIR}")

# 等待评审完成，读取问题清单
issues_file = "${OUTPUT_DIR}/.review/issues.md"

若评审失败 → 报告错误并终止。

Phase 7：Fix Issues（MANDATORY AUTO）

自动执行，无需用户确认。 根据 impl-review 输出的问题清单自动修复。

7.1 问题加载与分级处理

ISSUES_FILE="${OUTPUT_DIR}/.review/issues.md"
python3 - <<'EOF'
import re, pathlib
content = pathlib.Path("${ISSUES_FILE}").read_text()
issues = re.findall(r'###\s+\[([A-Z]+-\d+)\].*?Severity:\s+(CRITICAL|HIGH|MEDIUM|LOW)', content, re.DOTALL)
critical = [i for i in issues if i[1] == 'CRITICAL']
high = [i for i in issues if i[1] == 'HIGH']
print(f"CRITICAL: {len(critical)}, HIGH: {len(high)}")
EOF

7.2 修复执行顺序

修复优先级：CRITICAL → HIGH → MEDIUM
每个问题修复后立即运行综合检查验证

7.3 修复迭代与重审

  • 若仍有 CRITICAL/HIGH 问题 → 重复 Phase 7（最多 3 轮）
  • 若 3 轮后仍有 CRITICAL/HIGH → 标记 blocked，请求用户介入

7.4 修复完成标准

标准 要求
CRITICAL issues 0
HIGH issues 0
MEDIUM issues 允许存在（输出警告）
Synthesis check 无 CRITICAL/HIGH

Phase 8：Traceability CSV 生成 + Push to Remote

8.1 生成 impl phase CSV

从 RTL 文件中的 @requirement 注释扫描 REQ_ID，生成 traceability/requirements_matrix.impl.csv：

uv run $PROJECT_SCRIPTS/babel_traceability.py impl
uv run $PROJECT_SCRIPTS/babel_traceability.py src

8.2 唯一性检查

uv run $PROJECT_SCRIPTS/check_req_uniqueness.py --check-deleted

8.3 Push

git push

Error Handling

Scenario Action Skip?
MAS 文件 < 2 拒绝执行，返回 bb-mas ❌ NO
子模块未完成 禁止父模块 ❌ NO
综合检查 CRITICAL 立即修复 ❌ NO
端口定义不一致 立即修复 ❌ NO
FSM 编码不一致 立即修复 ❌ NO
impl-review 执行失败 报告错误，终止 ❌ NO
Fix Issues 测试失败 Debug loop (max 5) ❌ NO
Fix Issues 3 轮仍有 CRITICAL/HIGH Mark blocked, ask user ⚠️ Ask
Debug > 10 still FAIL Mark blocked, ask user ⚠️ Ask

Commit Strategy

Per-module commits（granular for rollback）：

git commit -m "feat({{ MODULE_ID }}): implement {{ MODULE_ID }} RTL

Leaf-to-parent complete
Synthesis check: passed
Checklist: {{ ITEMS_PASSED }}/total"

Module Complete Checkpoint

touch {{ CHECKPOINT_DIR }}/{{ MODULE_ID }}.done

写入 progress JSON 到 {{ PROGRESS_DIR }}/{{ MODULE_ID }}.json

最终验证清单

  • 所有叶子模块 RTL 文件存在
  • 端口定义与 MAS.md §2.1 一致
  • FSM 状态编码与 FSM.md 一致
  • 综合性检查通过（无 CRITICAL/HIGH）
  • Testbench 文件存在
  • impl-review 无 CRITICAL/HIGH 问题
  • frontmatter 格式正确

Key Principles

Principle Level
全程自动执行，不在 phase/batch 间暂停确认 🔴 MANDATORY
叶子优先执行顺序 🔴 MANDATORY
可综合性检查必须通过 🔴 MANDATORY
Gap Analysis + 死代码检测（synthesis） 🔴 MANDATORY
Debug iteration（no skip/bypass） 🔴 MANDATORY
彻底完成，不接受"足够好" 🔴 MANDATORY
同层并行（无冲突） 🟢 RECOMMENDED
冲突检测后再并行 🔴 MANDATORY
Per-module checkpoint 🔴 MANDATORY
Per-module commit 🔴 MANDATORY
Spec snapshot after successful run 🔴 MANDATORY
增量更新 via change detection 🔴 MANDATORY
/compact after each batch 🟡 RECOMMENDED
自动调用 bb-code-review 🔴 MANDATORY
自动修复所有 CRITICAL/HIGH 问题 🔴 MANDATORY

Output Structure

PROJECT_DIR/
├── spec_mas/            # INPUT_DIR
├── rtl/                 # OUTPUT_DIR
│   ├── .checkpoint/     # Module checkpoints (.done files)
│   ├── .progress/       # Progress tracking (.json files)
│   ├── .review/         # impl-review output
│   ├── M01/src/         # RTL source files
│   ├── M01/tb/          # Testbench files
│   └── rtl_tree.md      # RTL module tree
└── temp/deleted/        # Archived removed modules

参考文档

详见 references/ 目录：

  • sv_coding_style.md — SystemVerilog 编码规范
  • synthesizable_rules.md — 可综合性指南

项目级 Coding Style 参考：

  • wiki/codingstyle/systemverilog_styleguide.md — SystemVerilog Style Guide (systemverilog.io)
  • wiki/codingstyle/freescale_verilog_standard.md — Freescale Verilog HDL Coding Standard SRS V3.2

辅助脚本

详见 scripts/ 目录：

  • synthesis_check.py — 综合性检查

常见陷阱

详见 Gotcha/ 目录：

  • rtl_pitfalls.md — RTL 编码常见陷阱

常见借口（均无效）

Agent 的借口 为什么错
"这个模块很简单，不需要 FSM" 没有 FSM 意味着状态逻辑隐藏，调试困难
"initial 块只是用来初始化寄存器" 综合工具忽略 initial，仿真与综合不一致
"delay 语句用于仿真调试" delay 导致仿真时序与实际硬件不一致
"先写 RTL，再回过头补充 testbench" 无 testbench 无法验证功能正确性
"父模块可以先写，子模块并行实现" 父模块端口连接依赖子模块接口定义
"只有一个 latch 问题不大" 锁存器会导致时序分析和功耗问题

Evolution Trigger Point

When any Phase fails or user triggers /evolve:

  1. Detect failure: Read {{ OUTPUT_DIR }}/execution.log
  2. Invoke framework:
    bash {{ EVOLUTION_FRAMEWORK }}/evolve.sh \
  --skill "{{ SKILL_FILE }}" \
  --output "{{ OUTPUT_DIR }}" \
  --failure-phase "{{ FAILED_PHASE }}"
  3. Framework handles: Analyze, modify, validate, rollback
  4. Retry or escalate

Похожие навыки: other

limits-colimits

Context management for Claude Code. Hooks maintain state via ledgers and handoffs. MCP execution without context polluti...

Автор: parcadei
3,392

ddttom-allaboutv2-claude-skills-block-collection-and-party

The Block Collection and Block Party are repositories for existing AEM blocks, build tools, code snippets, integration p...

Автор: mattnigh
20

nodnarbnitram-claude-code-extensions-claude-skills-esphome-confi

This skill should be used when the user asks to "create an esphome config", "set up an esp32 device", "configure esphome...

Автор: mattnigh
20