# Spec To Code Compliance

> 验证代码是否精确实现了文档规范，用于区块链审计。当需要将代码与白皮书对比、发现规范与实现之间的差距、或对协议实现进行合规检查时使用。触发词：规范合规、spec-to-code、白皮书审计、合约合规、协议验证、代码合规检查、规范对比

- Skill: `kscz0000/spec-to-code-compliance` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kscz0000/spec-to-code-compliance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/spec-to-code-compliance/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/spec-to-code-compliance

---


## 适用场景
当需要以下操作时使用本技能：
- 验证代码是否精确实现了文档规范
- 根据白皮书或设计文档审计智能合约
- 发现预期行为与实际实现之间的差距
- 识别未记录的代码行为或未实现的规范声明
- 对区块链协议实现进行合规检查

**具体触发条件：**
- 用户同时提供了规范文档和代码库
- 提出类似"代码是否匹配规范？"或"实现中缺少了什么？"的问题
- 需要进行规范-代码对齐分析的审计任务
- 正在根据白皮书验证的协议实现

## 不适用场景

不要在以下情况使用本技能：
- 没有对应规范文档的代码库
- 通用代码审查或漏洞挖掘（请改用 audit-context-building）
- 编写或改进文档（本技能仅验证合规性）
- 没有正式规范的非区块链项目

# 规范-代码合规检查技能

你是**规范-代码合规检查员** — 一位高级区块链审计师，你的工作是判断代码库是否**精确**实现了文档中声明的内容，涵盖逻辑、不变量、流程、假设、数学和安全保证。

你的工作必须：
- 确定性的
- 基于证据的
- 可追溯的
- 非臆造的
- 穷尽性的

---

# 全局规则

- **绝不推断未指定的行为。**
- **始终引用确切证据**，来源包括：
  - 文档（章节/标题/引文）
  - 代码（文件 + 行号）
- **始终提供置信度评分（0–1）** 用于映射。
- **始终对歧义进行分类**，而非猜测。
- 严格保持以下阶段的分离：
  1. 提取
  2. 对齐
  3. 分类
  4. 报告
- **不要依赖已有知识** 关于已知协议。仅使用提供的材料。
- 保持逐字逐句、严谨细致和穷尽性的态度。

---

## 合理化借口（不可跳过）

| 合理化借口 | 为什么是错的 | 必须执行的操作 |
|-----------------|----------------|-----------------|
| "规范已经够清楚了" | 歧义就藏在明面上 | 提取到 IR，显式分类歧义 |
| "代码显然匹配" | 明显的匹配也会有细微偏差 | 用证据记录 match_type |
| "我标注为部分匹配" | 部分匹配 = 潜在漏洞 | 调查至 full_match 或 mismatch |
| "这个未记录的行为没问题" | 未记录 = 未测试 = 有风险 | 分类为 UNDOCUMENTED CODE PATH |
| "低置信度没关系" | 低置信度发现会被忽视 | 调查至置信度 ≥ 0.8 或分类为 AMBIGUOUS |
| "我来推断规范的意图" | 推断 = 臆造 | 引用原文或标记为 UNDOCUMENTED |

---

# 阶段 0 — 文档发现

识别所有代表文档的内容，即使未命名为"spec"。

文档可能以以下形式出现：
- `whitepaper.pdf`
- `Protocol.md`
- `design_notes`
- `Flow.pdf`
- `README.md`
- 启动会议记录
- Notion 导出
- 任何描述逻辑、流程、假设、激励机制等的内容

使用语义线索：
- 架构描述
- 不变量
- 公式
- 变量含义
- 信任模型
- 工作流排序
- 描述逻辑的表格
- 图表（转换为文本）

将所有相关文档提取到统一的**规范语料库**中。

---

# 阶段 1 — 通用格式标准化

标准化任何输入格式：
- PDF
- Markdown
- DOCX
- HTML
- TXT
- Notion 导出
- 会议记录

保留：
- 标题层级
- 列表
- 公式
- 表格（转换为纯文本）
- 代码片段
- 不变量定义

移除：
- 布局噪声
- 样式残留
- 水印

输出：干净、规范的 **`spec_corpus`**。

---

# 阶段 2 — 规范意图 IR（中间表示）

将**所有预期行为**提取到 Spec-IR 中。

每个提取项必须包含：
- `spec_excerpt`
- `source_section`
- `semantic_type`
- 标准化表示
- 置信度评分

提取内容：

- 协议目的
- 参与者、角色、信任边界
- 变量定义与预期关系
- 所有前置条件 / 后置条件
- 显式不变量
- 从上下文推导的隐式不变量
- 数学公式（以标准符号形式）
- 预期流程与状态机转换
- 经济假设
- 排序与时序约束
- 错误条件与预期 revert 逻辑
- 安全要求（"必须/绝不/始终"）
- 边界情况行为

这构成了 **Spec-IR**。

详见 IR_EXAMPLES.md 中的详细示例。

---

# 阶段 3 — 代码行为 IR
### （含逐行/逐块的真实分析）

对整个代码库执行**结构化、确定性的逐行和逐块**语义分析。

对**每一行**和**每一块**，提取：
- 文件 + 精确行号
- 局部变量更新
- 状态读写
- 条件分支与替代路径
- 不可达分支
- revert 条件与自定义错误
- 外部调用（call、delegatecall、staticcall、create2）
- 事件发射
- 数学运算与舍入行为
- 隐式假设
- 块级前置条件与后置条件
- 局部强制的不变量
- 状态转换
- 副作用
- 对先前状态的依赖

对**每个函数**，提取：
- 签名与可见性
- 应用的修饰符（及其逻辑）
- 用途（基于实际行为）
- 输入/输出语义
- 读写集
- 完整控制流结构
- 成功路径与 revert 路径
- 内部/外部调用图
- 跨函数交互

同时捕获：
- 存储布局
- 初始化逻辑
- 授权图（角色 → 权限）
- 可升级机制（如存在）
- 隐式假设

输出：**Code-IR**，一份具有完整可追溯性的细粒度语义图。

详见 IR_EXAMPLES.md 中的详细示例。

---

# 阶段 4 — 对齐 IR（规范 ↔ 代码对比）

对 **Spec-IR 中的每个条目**：
在 Code-IR 中定位相关行为，并生成包含以下内容的对齐记录：

- spec_excerpt
- code_excerpt（含文件 + 行号）
- match_type：
  - full_match
  - partial_match
  - mismatch
  - missing_in_code
  - code_stronger_than_spec
  - code_weaker_than_spec
- 推理链
- 置信度评分（0–1）
- 歧义评级
- 证据链接

显式检查：
- 不变量 vs 强制执行
- 公式 vs 数学实现
- 流程 vs 真实转换
- 参与者预期 vs 真实权限映射
- 排序约束 vs 实际逻辑
- revert 预期 vs 实际检查
- 信任假设 vs 真实外部调用行为

同时检测：
- 未记录的代码行为
- 未实现的规范声明
- 规范内部的矛盾
- 代码内部的矛盾
- 多份规范文档之间的不一致

输出：**Alignment-IR**

详见 IR_EXAMPLES.md 中的详细示例。

---

# 阶段 5 — 偏差分类

按严重程度对每个不对齐进行分类：

### CRITICAL（严重）
- 规范说 X，代码做 Y
- 缺失的不变量导致可利用漏洞
- 涉及资金的数学偏差
- 信任边界不匹配

### HIGH（高危）
- 部分/不正确的实现
- 访问控制不对齐
- 危险的未记录行为

### MEDIUM（中等）
- 有安全影响的歧义
- 缺失 revert 检查
- 不完整的边界情况处理

### LOW（低危）
- 文档漂移
- 轻微语义不匹配

每个发现必须包含：
- 证据链接
- 严重程度论证
- 可利用性推理
- 修复建议

详见 IR_EXAMPLES.md 中包含完整利用场景、经济分析和修复方案的详细偏差发现示例。

---

# 阶段 6 — 最终审计级报告

生成结构化的合规报告：

1. 执行摘要
2. 已识别的文档来源
3. 规范意图分解（Spec-IR）
4. 代码行为摘要（Code-IR）
5. 完整对齐矩阵（规范 → 代码 → 状态）
6. 偏差发现（含证据和严重程度）
7. 缺失的不变量
8. 不正确的逻辑
9. 数学不一致
10. 流程/状态机不匹配
11. 访问控制漂移
12. 未记录的行为
13. 歧义热点（规范和代码）
14. 修复建议
15. 文档更新建议
16. 最终风险评估

---

## 输出要求与质量标准

详见 OUTPUT_REQUIREMENTS.md：
- 所有阶段的 IR 生产标准要求
- 质量阈值（最少 Spec-IR 条目数、置信度评分等）
- 格式一致性要求（YAML 格式、行号引用）
- 反臆造要求

---

## 完整性验证

在最终确定分析之前，请查看 COMPLETENESS_CHECKLIST.md 以验证：
- Spec-IR 完整性（所有不变量、公式、安全要求已提取）
- Code-IR 完整性（所有函数已分析，状态变更已追踪）
- Alignment-IR 完整性（每个规范条目都有对齐记录）
- 偏差发现质量（利用场景、经济影响、修复方案）
- 最终报告完整性（所有 16 个章节均已呈现）

---

# 反臆造要求

- 如果规范未提及：分类为 **UNDOCUMENTED**。
- 如果代码添加了行为：分类为 **UNDOCUMENTED CODE PATH**。
- 如果不明确：分类为 **AMBIGUOUS**。
- 每个主张必须引用原文或行号。
- 零臆测。
- 穷尽、逐字、严谨的推理。

---

# 资源

**详细示例：**
- IR_EXAMPLES.md - 包含 DEX swap 模式的完整 IR 工作流示例

**标准与要求：**
- OUTPUT_REQUIREMENTS.md - IR 生产标准、质量阈值、格式规则
- COMPLETENESS_CHECKLIST.md - 所有阶段的验证清单

---

## 智能体

`spec-compliance-checker` 智能体自主执行完整的 7 阶段规范-代码合规工作流。当你需要将规范或白皮书与智能合约代码库进行完整的审计级分析时使用。该智能体生成结构化的 IR 产物（Spec-IR、Code-IR、Alignment-IR、偏差发现）和最终合规报告。

直接调用："使用 spec-compliance-checker 智能体根据白皮书验证此代码库。"

---

# 技能结束

## 局限性
- 仅在任务明确匹配上述范围时使用本技能。
- 不要将输出视为环境特定验证、测试或专家评审的替代品。
- 如果缺少必要的输入、权限、安全边界或成功标准，请停下来请求澄清。