code-to-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec Extractor

规范提取器

Purpose

用途

Extract a behavioral specification from a source-code bundle — anywhere from ≤6 files up to a 500+ file application. The output is detailed enough that another engineer or LLM could rebuild the same observable behavior in any language or framework without reading the original source.

The skill orchestrates a pipeline of bundled plugin agents: a scout that maps structure, module analyzers that produce medium-depth summaries, a contract resolver for cross-module events and exports, deep analyzers for flagged critical modules, an auditor that verifies the spec against source, and a synthesizer that assembles the final output directory.

从源代码包中提取行为规范——范围从≤6个文件到包含500多个文件的应用程序。输出内容足够详细，其他工程师或LLM无需阅读原始源代码，即可在任意语言或框架中重建相同的可观测行为。

该技能编排了一套捆绑插件Agent的流水线：负责映射结构的侦察Agent、生成中等深度摘要的模块分析Agent、处理跨模块事件与导出的契约解析Agent、针对标记关键模块的深度分析Agent、验证规范与源代码一致性的审计Agent，以及组装最终输出目录的合成Agent。

When to Use

使用场景

User says: "extract a spec from X", "analyze what X does", "understand X's contract", "reverse engineer", "produce a reimplementation spec".
User wants to understand a whole application or a specific module in detail.
User wants a reproducible, stack-neutral spec — not documentation, not an API reference, but a behavioral contract.

用户提出：“从X中提取规范”、“分析X的功能”、“理解X的契约”、“逆向工程”、“生成重实现规范”。
用户希望详细理解整个应用或特定模块。
用户需要可复现、与技术栈无关的规范——不是文档，不是API参考，而是行为契约。

Invocation Modes

调用模式

Three forms, detected at invocation time:

Form	Example	Skill interpretation
No args	`/code-to-spec`	Walk the active repo from the working directory
Paths	`/code-to-spec src/foo src/bar.ts modules/lib/src`	Explicit files / folders; folders expanded
Guide	`/code-to-spec auth flow` , `/code-to-spec the message bus`	Natural-language scope — skill searches with Grep/Glob and proposes a file list

Detection rule: if every argument resolves to an existing file or directory on disk → paths mode. Otherwise → guide mode.

三种形式，在调用时自动检测：

形式	示例	技能解读
无参数	`/code-to-spec`	从工作目录遍历当前仓库
路径	`/code-to-spec src/foo src/bar.ts modules/lib/src`	明确指定文件/文件夹；文件夹会展开
引导词	`/code-to-spec auth flow` , `/code-to-spec the message bus`	自然语言范围——技能通过Grep/Glob搜索并提议文件列表

检测规则： 如果每个参数都对应磁盘上存在的文件或目录 → 路径模式。否则 → 引导词模式。

Tiers

层级划分

The skill auto-selects a tier based on resolved bundle size:

Tier	Range	Pipeline
Small	≤ 6 files or ≤ 1500 LOC	`spec-analyzer` → `spec-auditor` → single-file output
Medium	7–30 files	`spec-scout` → parallel `spec-module-analyzer` → `spec-contract-resolver` → `spec-synthesizer` → `spec-auditor`
Large	31+ files, up to 500+	Medium pipeline + parallel `spec-analyzer` deep dives on flagged critical modules

技能会根据解析后的包大小自动选择层级：

层级	范围	流水线
小型	≤6个文件或≤1500行代码	`spec-analyzer` → `spec-auditor` → 单文件输出
中型	7–30个文件	`spec-scout` → 并行 `spec-module-analyzer` → `spec-contract-resolver` → `spec-synthesizer` → `spec-auditor`
大型	31+个文件，最多500+个	中型流水线 + 针对标记关键模块的并行 `spec-analyzer` 深度分析

Dependencies

依赖项

Bundled plugin agents (

review/agents/

```
review:spec-scout
```
— architecture map + module inventory + critical-module nomination
```
review:spec-module-analyzer
```
— medium-depth per-module summary
```
review:spec-analyzer
```
— deep 11-section spec per module
```
review:spec-contract-resolver
```
— cross-module events, exports, integrations
```
review:spec-synthesizer
```
— aggregation and final file assembly
```
review:spec-auditor
```
— verification against source

References:

```
references/spec-template.md
```
— unified output schema
```
references/severity-rubric.md
```
— Critical/Warning/Note definitions (mirrors auditor)
```
references/calibration-guide.md
```
— forward-looking guidance for a future calibration skill

捆绑插件Agent（

review/agents/

）：

```
review:spec-scout
```
— 架构图 + 模块清单 + 关键模块提名
```
review:spec-module-analyzer
```
— 每个模块的中等深度摘要
```
review:spec-analyzer
```
— 每个模块的11节深度规范
```
review:spec-contract-resolver
```
— 跨模块事件、导出、集成
```
review:spec-synthesizer
```
— 汇总与最终文件组装
```
review:spec-auditor
```
— 与源代码的一致性验证

参考文件：

```
references/spec-template.md
```
— 统一输出 schema
```
references/severity-rubric.md
```
— 严重/警告/说明定义（与审计Agent同步）
```
references/calibration-guide.md
```
— 为未来校准技能提供前瞻性指导

Workflow

工作流程

Phase 1: Scope Resolution

阶段1：范围解析

Step 1: Resolve mode.

$ARGUMENTS

is empty → whole-repo mode. Set

roots = ["."]

Else, test each argument against the filesystem. If every argument is a readable file or directory → paths mode. Set

roots = <arguments>

. Otherwise → guide mode. Set

guide = $ARGUMENTS

Step 2: Collect candidate files.

For paths mode and whole-repo mode: use

Glob

on each root for these extensions by default:

**/*.{ts,tsx,js,jsx,mjs,cjs}

Apply exclusion filter (unconditional):

```
**/node_modules/**
```

**/build/**

**/dist/**

**/out/**

**/.build/**

**/target/**

```
**/*.d.ts
```
```
**/*.test.*
```
,
```
**/*.spec.*
```
,
```
**/__tests__/**
```
```
**/.git/**
```
Any path matched by
```
.gitignore
```
(read
```
.gitignore
```
and honor its patterns)

For guide mode: use the guide string to drive

Grep

across the project (case-insensitive, token-split). Rank candidate files by number of hits. Take the top 20–40 files as the provisional bundle. Then apply the exclusion filter.

Step 3: Count and select tier.

file_count = number of files after filtering
loc = sum of line counts (use `Bash: wc -l` for speed)
tier = Small if file_count ≤ 6 or loc ≤ 1500
       Medium if file_count ≤ 30
       Large otherwise

Step 4: Confirm bundle with the user.

Present a summary and use

AskUserQuestion

Bundle resolved:
- Mode: <whole-repo | paths | guide>
- Files: N
- LOC: N
- Tier: <Small | Medium | Large>
- Roots: <list>
- Language(s): <detected>

Question: "Proceed with this bundle?"

Proceed (Recommended) — begin analysis
Narrow — re-ask with a narrower guide or path set
Edit — user supplies a trimmed file list
Cancel — abort

Budget gates:

If
```
file_count > 200
```
: include a warning in the bundle summary — "This will dispatch approximately N parallel agents over M minutes. Confirm to proceed."
If
```
file_count > 500
```
: recommend narrowing first. Still allow Proceed if the user insists.

步骤1：解析模式

如果

$ARGUMENTS

为空 → 全仓库模式。设置

roots = ["."]

。

否则，测试每个参数是否对应文件系统中的资源。如果所有参数都是可读文件或目录 → 路径模式。设置

roots = <arguments>

。否则 → 引导词模式。设置

guide = $ARGUMENTS

。

步骤2：收集候选文件

对于路径模式和全仓库模式：默认对每个根目录使用

Glob

匹配以下扩展名：

**/*.{ts,tsx,js,jsx,mjs,cjs}

。

应用排除过滤器（无条件）：

```
**/node_modules/**
```

**/build/**

**/dist/**

**/out/**

**/.build/**

**/target/**

```
**/*.d.ts
```
```
**/*.test.*
```
,
```
**/*.spec.*
```
,
```
**/__tests__/**
```
```
**/.git/**
```
```
.gitignore
```
匹配的任何路径（读取
```
.gitignore
```
并遵循其规则）

对于引导词模式：使用引导字符串在项目中执行

Grep

搜索（不区分大小写，按分词匹配）。按命中次数对候选文件排序。选取前20–40个文件作为临时包，然后应用排除过滤器。

步骤3：计数并选择层级

file_count = 过滤后的文件数量
loc = 总行数（使用`Bash: wc -l`提高速度）
tier = Small 如果 file_count ≤6 或 loc ≤1500
       Medium 如果 file_count ≤30
       Large 否则

步骤4：与用户确认包内容

展示摘要并调用

AskUserQuestion

：

已解析包内容：
- 模式：<全仓库 | 路径 | 引导词>
- 文件数：N
- 代码行数：N
- 层级：<Small | Medium | Large>
- 根目录：<列表>
- 语言：<检测结果>

问题：“是否继续处理此包？”

继续（推荐）——开始分析
缩小范围——使用更窄的引导词或路径重新询问
编辑——用户提供精简后的文件列表
取消——终止操作

预算限制：

如果
```
file_count >200
```
：在包摘要中添加警告——“这将在大约M分钟内调度N个并行Agent。确认后继续。”
如果
```
file_count >500
```
：建议先缩小范围。如果用户坚持，仍允许继续。

Phase 2: Destination

阶段2：目标位置

Step 5: Choose destination root.

AskUserQuestion

docs/
(Recommended) — project-visible, likely versioned
.claude/docs/
— agent-scoped, typically gitignored
/tmp/
— scratch, ephemeral (timestamped filenames)
Other — user supplies a custom path

Step 6: Collision handling.

Determine target:

Small tier →
```
<dest>/spec.md
```
(file)
Medium / Large tier →
```
<dest>/spec/
```
(directory)

Check if the target exists. If yes,

AskUserQuestion

spec-<N>.md
/
spec-<N>/
(Recommended) — auto-incremented
spec-<name>.md
/
spec-<name>/
— user supplies
```
<name>
```
Overwrite — replace existing content
Other — custom filename / subdirectory

/tmp/

always uses timestamped names, skip collision check.

步骤5：选择目标根目录

调用

AskUserQuestion

：

docs/
（推荐）——项目可见，通常已纳入版本控制
.claude/docs/
——Agent专属范围，通常被git忽略
/tmp/
——临时目录，文件带有时间戳
其他——用户提供自定义路径

步骤6：冲突处理

确定目标：

小型层级 →
```
<dest>/spec.md
```
（文件）
中型/大型层级 →
```
<dest>/spec/
```
（目录）

检查目标是否存在。如果存在，调用

AskUserQuestion

：

spec-<N>.md
/
spec-<N>/
（推荐）——自动递增命名
spec-<name>.md
/
spec-<name>/
——用户提供
```
<name>
```
覆盖——替换现有内容
其他——自定义文件名/子目录

/tmp/

始终使用时间戳命名，跳过冲突检查。

Phase 3: Pipeline Dispatch

阶段3：流水线调度

Resolve the temp directory:

bash

bash -c 'printf "%s" "${TMPDIR:-/tmp}"'

Use it as

<TMP>

. Create a session subdirectory:

<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/

解析临时目录：

bash

bash -c 'printf "%s" "${TMPDIR:-/tmp}"'

将其作为

<TMP>

。创建会话子目录：

<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/

。

Small Tier

小型层级

Skip scout, module analyzers, contract resolver, synthesizer.

Dispatch
spec-analyzer
via
```
Task
```
:
- ```
subagent_type: "review:spec-analyzer"
```
- ```
model: "opus"
```
- ```
prompt
```
  : file list + role hints + instruction to follow its agent contract

Write raw analyzer output to

<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/analyzer.md

Dispatch
spec-auditor
via

Task

```
subagent_type: "review:spec-auditor"
```
```
model: "opus"
```
```
prompt
```
: mode=
```
per-module
```
, source file list, path to analyzer output

Write raw auditor output to

<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/auditor.md

Assemble final file. Use
```
Write
```
to produce
```
<dest>/spec.md
```
:

markdown

undefined

跳过侦察、模块分析、契约解析和合成步骤。

**调度
```
spec-analyzer
```
**通过
```
Task
```
：
- ```
subagent_type: "review:spec-analyzer"
```
- ```
model: "opus"
```
- ```
prompt
```
  : 文件列表 + 角色提示 + 遵循其Agent契约的指令

写入分析器原始输出到

<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/analyzer.md

。

**调度

spec-auditor

**通过

Task

：

```
subagent_type: "review:spec-auditor"
```
```
model: "opus"
```
```
prompt
```
: mode=
```
per-module
```
, 源文件列表, 分析器输出路径

写入审计器原始输出到

<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/auditor.md

。

组装最终文件。使用
```
Write
```
生成
```
<dest>/spec.md
```
：

markdown

undefined

Behavioral Specification

行为规范

Bundle: <bundle-name> Generated: <ISO 8601> Files: N Tier: Small

包： <包名称> 生成时间： <ISO 8601格式> 文件数： N 层级： Small

<分析器输出原文>

Audit Findings

审计结果

<auditor output verbatim> ```

Report. Print output path +
```
N Critical / N Warning / N Note
```
.

<审计器输出原文>


6. **报告**。打印输出路径 + `N个严重问题 / N个警告 / N个说明`。

Medium Tier

中型层级

Scout pass. Single

Task

dispatch:

```
subagent_type: "review:spec-scout"
```
```
model: "opus"
```
```
prompt
```
: bundle file list, file count, LOC, tier

Write output to

<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/scout.md

Parse modules from scout output. Extract the Module Inventory table. For each row, collect the module name, path, and file subset.
Parallel module analysis. Dispatch
```
spec-module-analyzer
```
per module, capped at 5 concurrent. For larger module counts, dispatch in batches of 5 in successive messages.
- Each dispatch:
```
subagent_type: "review:spec-module-analyzer"
```
  ,
```
model: "opus"
```
  , prompt contains module name, role, files, and scout excerpt.
- Write each output to
```
<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/modules/<module-name>.md
```
  .
Contract resolution. Single
```
Task
```
dispatch once all module analyzers return:
- ```
subagent_type: "review:spec-contract-resolver"
```
- ```
model: "opus"
```
- ```
prompt
```
  : scout output + all module summaries + full file list
- Write to
```
<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/contracts.md
```

Per-module audit. Dispatch

spec-auditor

per module, capped at 5 concurrent. Mode=

per-module

. Write each to

<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/audit/<module-name>.md

Global audit. Single
```
spec-auditor
```
dispatch, mode=
```
global
```
, with scout + modules + contracts. Write to
```
<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/audit-global.md
```
.
Synthesis. Single
```
spec-synthesizer
```
dispatch:
- ```
subagent_type: "review:spec-synthesizer"
```
- ```
model: "sonnet"
```
- ```
prompt
```
  : destination path, tier, bundle summary, and absolute paths to all upstream output files
- Synthesizer writes the final directory.
Report. Print output directory path + consolidated severity totals.

侦察阶段。单次

Task

调度：

```
subagent_type: "review:spec-scout"
```
```
model: "opus"
```
```
prompt
```
: 包文件列表, 文件数, 代码行数, 层级

将输出写入

<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/scout.md

从侦察输出中解析模块。提取模块清单表格。为每一行收集模块名称、路径和文件子集。
并行模块分析。为每个模块调度
```
spec-module-analyzer
```
，并发数上限为5。如果模块数量较多，分批次每次调度5个，通过连续消息发送。
- 每个调度：
```
subagent_type: "review:spec-module-analyzer"
```
  ,
```
model: "opus"
```
  , prompt包含模块名称、角色、文件和侦察摘要。
- 将每个输出写入
```
<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/modules/<module-name>.md
```
  。
契约解析。所有模块分析完成后，单次
```
Task
```
调度：
- ```
subagent_type: "review:spec-contract-resolver"
```
- ```
model: "opus"
```
- ```
prompt
```
  : 侦察输出 + 所有模块摘要 + 完整文件列表
- 写入
```
<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/contracts.md
```
逐模块审计。为每个模块调度
```
spec-auditor
```
，并发数上限为5。模式=
```
per-module
```
。将每个输出写入
```
<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/audit/<module-name>.md
```
。
全局审计。单次
```
spec-auditor
```
调度，模式=
```
global
```
，输入侦察+模块+契约内容。写入
```
<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/audit-global.md
```
。
合成。单次
```
spec-synthesizer
```
调度：
- ```
subagent_type: "review:spec-synthesizer"
```
- ```
model: "sonnet"
```
- ```
prompt
```
  : 目标路径, 层级, 包摘要, 所有上游输出文件的绝对路径
- 合成器写入最终目录。
报告。打印输出目录路径 + 汇总的严重问题统计。

Large Tier

大型层级

Steps 1–4 identical to Medium tier. Then:

Module review (optional). Present the scout's nominated critical modules to the user.
```
AskUserQuestion
```
:
- Proceed with scout's selection (Recommended)
- Add modules — user specifies additional modules for deep analysis
- Remove modules — user trims the list
- Skip deep dives — proceed Medium-style
Deep analysis. For each flagged critical module, dispatch
```
spec-analyzer
```
, capped at 3 concurrent. Write each to
```
<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/deep/<module-name>.md
```
.
Per-module audit — as Medium step 5, but include per-module deep spec as audit input when available.
Global audit — as Medium step 6.
Synthesis — as Medium step 7, with
```
deep/
```
paths included in the synthesizer's input list.
Report — as Medium step 8.

步骤1–4与中型层级相同。然后：

模块审查（可选）。向用户展示侦察Agent提名的关键模块。调用
```
AskUserQuestion
```
：
- 使用侦察Agent的选择（推荐）
- 添加模块——用户指定需要深度分析的额外模块
- 移除模块——用户精简列表
- 跳过深度分析——按中型层级流程继续
深度分析。为每个标记的关键模块调度
```
spec-analyzer
```
，并发数上限为3。将每个输出写入
```
<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/deep/<module-name>.md
```
。
逐模块审计——与中型层级步骤5相同，但如果有逐模块深度规范，则将其作为审计输入。
全局审计——与中型层级步骤6相同。
合成——与中型层级步骤7相同，但在合成器的输入列表中包含
```
deep/
```
路径。
报告——与中型层级步骤8相同。

Phase 4: Error Handling

阶段4：错误处理

Missing file path — abort before Phase 1 Step 2 completes. Name the failing path.
Empty resolved bundle — refuse with a clear message and stop.
Scout failure — abort pipeline, report failure. No partial files written.
Module analyzer failure on one module — skip that module; log it; continue. Synthesizer notes it under "Missing Coverage" in
```
audit.md
```
.
Contract resolver failure — synthesize without
```
contracts.md
```
; note in audit.
Deep analyzer failure on one module — skip that module's deep spec; note in audit; continue.
Synthesizer failure — save raw upstream outputs to
```
<dest>/spec/raw/
```
for debugging. Report failure.
Auditor failure (per-module) — continue; global audit still runs.
Auditor failure (global) — write spec without consolidated audit.md; note the gap in
```
README.md
```
.

路径不存在——在阶段1步骤2完成前终止。指出失败的路径。
解析后的包为空——明确拒绝并停止操作。
侦察Agent失败——终止流水线，报告失败。不写入任何部分文件。
单个模块分析Agent失败——跳过该模块；记录日志；继续。合成器会在
```
audit.md
```
的“缺失覆盖”部分注明。
契约解析Agent失败——不包含
```
contracts.md
```
进行合成；在审计中注明。
单个模块深度分析Agent失败——跳过该模块的深度规范；在审计中注明；继续。
合成Agent失败——将原始上游输出保存到
```
<dest>/spec/raw/
```
用于调试。报告失败。
逐模块审计失败——继续；全局审计仍会运行。
全局审计失败——写入不含汇总
```
audit.md
```
的规范；在
```
README.md
```
中注明该缺口。

Parallelism Caps

并发数上限

When dispatching N parallel Task subagents where N exceeds the cap, send them in batches of

cap

in successive messages. Caps:

```
spec-module-analyzer
```
: 5
```
spec-analyzer
```
(deep): 3
```
spec-auditor
```
: 5

The caps balance throughput against context and rate-limit pressure. Do not exceed without user direction.

当调度N个并行Task子Agent且N超过上限时，分批次每次发送

cap

个，通过连续消息发送。上限：

```
spec-module-analyzer
```
：5
```
spec-analyzer
```
（深度）：3
```
spec-auditor
```
：5

这些上限平衡了吞吐量与上下文和速率限制压力。未经用户指示不得超过。

Output Layout

输出结构

Small Tier

小型层级

<dest>/spec.md

<dest>/spec.md

Medium / Large Tier

中型/大型层级

<dest>/spec/
├── README.md
├── architecture.md
├── modules.md
├── contracts.md
├── audit.md
└── modules/
    └── <module>.md    (only flagged critical modules in Large tier)

<dest>/spec/
├── README.md
├── architecture.md
├── modules.md
├── contracts.md
├── audit.md
└── modules/
    └── <module>.md   （仅大型层级中的标记关键模块）

Quality Constraints (Non-negotiable)

质量约束（不可协商）

Domain-neutral prompts. No library, framework, or product names in any agent body or in the final output structure.
Evidence-first. Every claim in every output cites
```
file:line
```
or
```
file:start-end
```
.
Literal payloads. Event payloads, state assignments, and branch behaviors are transcribed as constructed in source, not paraphrased.
No placeholders. Every section in every output file is complete or explicitly marked N/A with reason.
Finish dropped. Markup, CSS, bundler config, exact private naming, stack-specific primitives — excluded from the spec.
Observable-behavior framing. Describe what gets emitted, routed, dropped — not syntactic shape.

领域无关提示。任何Agent主体或最终输出结构中不得包含库、框架或产品名称。
基于证据。每个输出中的所有声明都必须引用
```
file:line
```
或
```
file:start-end
```
。
字面负载。事件负载、状态赋值和分支行为必须按源代码中的构造转录，不得意译。
无占位符。每个输出文件中的每个部分要么完整，要么明确标记N/A并说明原因。
排除非核心内容。标记、CSS、打包器配置、精确私有命名、技术栈特定原语——均从规范中排除。
可观测行为视角。描述输出、路由、丢弃的内容——而非语法结构。

Rules

规则

Confirm the bundle before dispatching agents. Bundle size drives budget.
Tier auto-select, with user override via Narrow/Edit.
Parallelism capped at agent-specific limits. Batched dispatch when counts exceed caps.

Temp files under
<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/
— left for OS cleanup.

No source modification. The skill only reads source and writes to the destination.
One run per invocation. Re-running overwrites only if the user accepts.

调度Agent前确认包内容。包大小决定预算。
自动选择层级，用户可通过缩小范围/编辑进行覆盖。
并发数受Agent特定上限限制。当数量超过上限时分批次调度。
临时文件存储在
<TMP>/code-to-spec-${CLAUDE_SESSION_ID}/
——由操作系统清理。
不修改源代码。该技能仅读取源代码并写入目标位置。
每次调用运行一次。重新运行仅在用户接受时才会覆盖内容。