reconstruct

Reconstruct：任意代码仓库，或任意创意 → 可构建的 PRD 套件

有关引擎证据和覆盖范围限制，请阅读 engine-evidence。

一个零依赖的 Node 脚本负责确定性脚手架（事实 + 候选提示）； 你负责提供适用于相应框架的理解——包括接口层面、数据模型和实际功能，适用于任何技术栈。输出是一个 PRD 文件夹，Agent 可据此重建项目，且无需访问原始项目或本次对话。

Markdown 就是程序。 引擎从不推理；所有判断都由你做出。

选择路径

用户想要	路径	从这里开始	然后阅读
重建 / 克隆 / 逆向工程某个代码仓库；将代码转化为规格	代码	node scripts/analyze.mjs --repo <REPO> --out <OUT>	procedure.md §路径 A
将创意转化为 PRD / 构建计划（尚无代码）	从零开始	先访谈——不运行命令	scratch-playbook.md、procedure.md §路径 B
决定要构建什么；探索概念	头脑风暴	node scripts/analyze.mjs --brainstorm --out <DIR>	brainstorm-playbook.md
继续 / 刷新已有的重建项目	恢复	node scripts/analyze.mjs --check --out <OUT>	procedure.md §路径 D
提供给 Agent 实现的单个文件	打包	node scripts/analyze.mjs --specs --out <OUT>（不带 --repo）	scale-and-context.md §6
在本地用例上比较重建程序与原程序	行为	先检查测试样例，并获取执行命令的授权	behavior-compare.md

使用已安装技能文件夹中 scripts/analyze.mjs 的绝对路径。--help 会列出所有标志。对于简单的单文件脚本，或用户现在想要可运行的应用而非计划时，请跳过此技能。

需确认的输入（代码路径）：目标代码仓库 · 输出目录 · 模式 preserve（保留架构）或 redesign（功能相同，采用全新架构）· 级别 light（忠实还原）或 complex（同时提出改进建议）· 保真度 mirror/embed/describe；若未设置，则根据模式和级别推导。

流程——四个阶段

# 1. SCAFFOLD — deterministic, no API key
node scripts/analyze.mjs --repo <REPO> --out <OUT> --mode <MODE> --level <LEVEL>

# 2. ORIENT — SUMMARY.md (~3 KB, written every run), NOT inventory.json (grows with the repo)
#    slice the inventory:  jq '.features[] | {slug, files: (.files|length)}' <OUT>/inventory.json
#    identify the stack → references/stack-guides/INDEX.md maps the label to its guide

# 3. ENRICH — fill INTERFACES.md, DATA-MODEL.md, ARCHITECTURE.md (+ DESIGN-SYSTEM.md for a UI),
#    then every features/<slug>/PRD.md to full spine depth. At scale, fan out:
node scripts/analyze.mjs --orchestrate --out <OUT> --phase enrich-map

# 4. CONVERGE — run to the fixpoint, autonomously, in one go
node scripts/analyze.mjs --check   --out <OUT>              # layer 1: structure
node scripts/analyze.mjs --review  --out <OUT>              # layer 2: worklist (changed units only)
#   → findings.json → --review --apply findings.json --out <OUT>
node scripts/analyze.mjs --verify  --out <OUT>              # faithfulness: requirement↔evidence
#   → verdicts.json → --verify --apply verdicts.json --out <OUT>
node scripts/analyze.mjs --check --semantic --out <OUT>     # the final, fail-closed gate

第 4 阶段是一个循环，不是检查清单：丰富 → 检查 → 审查 → 修复 → 验证 → 设门槛，直到 --check --semantic 以状态码 0 退出。规则、台账字段和停止条件统一定义在 convergence-loop.md 中。不要自行制定停止规则。

不容妥协的事项

• hints、routes 和 i18n 都只是待验证的线索，绝非事实。 打开源代码并确认。解决 inventory.unknowns 中的每一项。如果存在 inventory.warnings，说明这些区域的检测结果不完整，请手动检查。
• 解决并删除每一条 > 🧠 提示。 留下一条就意味着该单元尚未完成，且 --check 会失败。
• 务必全面，绝不只举例。 不要写“等等”或“诸如此类”，也不要只涵盖理想路径。只要存在某种行为、角色、验证规则或错误状态，就要为其单独列出一行。
• 记录契约，而非名称。 没有具体数值的速率限制、没有成员列表的枚举、没有请求格式的服务，都无法据此实现。十个类别见：buildability-checklist.md。
• 多写小型 PRD，少写宽泛的大型 PRD。 一个单元中超过约 5–7 个用户故事或约 3 个实体时，就拆分。每项独立能力都应有自己的 PRD。
• 绝不要在已丰富的目录树上重新运行分析器——它会重新渲染每份文档。CLI 会拒绝此操作；要继续处理现有目录树，请使用 --check/--review/--verify；要重新搭建脚手架，请将 --out 指向新目录。
• 每项断言都必须以 source//data/（代码模式）或 CONTEXT.md/ADR（草稿模式）为依据。 凭空编造的修复只会用一个问题换来另一个问题。
• 切勿让上限悄无声息地截断工作。 --verify 会限制其工作列表（默认 60 对），大量扇出也会限制 Agent 数量。查看 coverage，并报告实际覆盖的内容。
• 从头到尾负责整个循环。 亲自运行到修复点——不要把后续轮次交还给别人，不要问“要不要继续？”，也不要在第一轮后停下。只在最后汇报一次。
• 自检： 一个全新的 Agent 能否仅凭该单元的 PRD 和架构文档，正确地重建该单元——契约准确，而不只是大意？如果不能，就继续深入调查。worked-example.md 是深度标准。

编排——按运行环境选择路径

判断阶段会将独立的逐单元工作列表分发出去。--orchestrate 会根据 <OUT> 中当前的工作列表生成扇出任务，并写入绝对路径和实际单元 ID：

node scripts/analyze.mjs --orchestrate --out <OUT> [--phase enrich-map|review-find|review-verify|adjudicate] [--eco] [--list]

运行环境	如何运行每个判断阶段
Codex 或其他支持子 Agent 的宿主环境	使用 --orchestrate --phase <p>；按照 <OUT>/orchestration/agents/<role>.md，为每个批次分派一个子 Agent。子 Agent 返回片段；你负责一次性串行合并，并运行归并命令。
使用 Workflow 工具的 Claude Code	使用 --orchestrate --phase <p>，然后通过 Workflow 启动 <OUT>/orchestration/<p>.workflow.mjs。子 Agent 返回片段；你负责一次性串行合并，并运行打印出的归并命令。
Eco 模式或没有子 Agent	--orchestrate --eco → 按顺序遵循 <OUT>/orchestration/RUNBOOK.md，亲自承担每个角色。正确性完全相同，只有耗时不同。

扇出是优化手段，绝非必需——各道门槛都与运行环境无关，每个阶段都有产物相同的顺序执行后备方案。**子 Agent 不得写入：**归并操作（每份文档的合并、每次 --apply 归并）始终由你负责。绝不要扇出全新项目访谈、--brainstorm、归并步骤或草稿构建。工作列表尚不存在时运行 --phase <p> 会以状态码 2 退出，并指出生成该工作列表的命令。协议见：orchestration.md；规模与上下文见：scale-and-context.md。

参考索引

从这里开始

文件	何时阅读
procedure.md	执行工作时——四条路径的完整分步说明
convergence-loop.md	第 4 阶段——循环、台账以及何时停止
worked-example.md	编写第一份 PRD 之前——深度标准与反模式
troubleshooting.md	遇到任何故障、拒绝或无法变绿的情况

方法

文件	何时阅读
analysis-playbook.md	通用方法——没有技术栈指南时也适用
stack-guides/INDEX.md	**将技术栈标签映射到对应指南——不要猜文件名。**此索引列出了 references/stack-guides/ 中的每份速查表，包括无框架的情况（库/CLI/SDK）
buildability-checklist.md	十类契约检查项与一致性自查
architecture-analysis.md	填写 ARCHITECTURE.md，尤其是在 redesign 模式下
scale-and-context.md	代码库很大、属于单体仓库，或运行耗费的上下文过多时
adapters.md	inventory.routes 的解析方式，以及如何添加框架

检查关卡

文件	何时阅读
ai-review-rubric.md	第 2 层——九项语义级可构建性检查
verify-playbook.md	--verify——声明、证据、判定、置信度、上限
orchestration.md	如何通过子 Agent 并行进行信息补充和评审循环

从零开始与构思

文件	何时阅读
scratch-playbook.md	从零开始的访谈方法
scratch-plan-schema.md	编写 plan.json——架构与完整示例
CONTEXT-FORMAT.md · ADR-FORMAT.md	编写术语表/ADR
brainstorm-playbook.md	发散阶段，在作出任何决定之前

输出形式

文件	何时阅读
prd-light-template.md · prd-complex-template.md	各级别 PRD 的结构
rebuild-instructions.md	告知用户如何驱动重建

安全

分析器只会读取目标代码库，并将文件复制到输出目录。分析期间，它绝不会 执行被分析项目的代码。单独选择启用的 --compare <cases.json> --original <dir> --rebuilt <dir> --run-tests 模式会以本地用户权限执行 夹具命令。使用 --run-tests 前，请阅读每条命令并取得明确授权；若未启用该选项，案例将保持 not-tested，且检查关卡会失败。只报告实际运行的案例，以及 stdout/stderr/退出状态是否完全一致， 绝不声称全局等价。源代码忠实度台账和可构建性台账仍是独立的检查关卡。在不可信的代码库上运行前，请检查 scripts/。