nekolife1984/specback

# specback — 逆向规格说明书生成器 📖 **日本語版本在下方** — [跳转至日语版 →](#日本語版) `specback` 是一个通用框架，用于从遗留或现有代码库中自动生成面向维护工程师或最终客户的规格说明书。 它是 `cc-sdd`（Spec Driven Development，规格驱动开发）的**逆向**对应物：如果说 `cc-sdd` 走的是“规格 → 代码”，那么 `specback` 走的就是“代码 → 规格”。 ## 开发初衷 遗留系统的现代化改造、新工程师熟悉代码库、交付规格文档、内部知识整合——在所有这些场景中，“我们有代码，但没有可靠的规格说明书”这个问题是普遍存在的。 在 LLM 时代，要求 AI“根据这段代码生成一份规格说明书”可以瞬间产出排版精美的文档。但在实际操作中，如果这份文档最终被证明是“充满猜测的完美虚构”，它在生产环境中就会失效。 `specback` 优先考虑以下几点： - **诚实性**：不隐藏猜测——明确标记它们。将“未决事项”作为单独的章节展示 - **可追溯性**：每一条陈述都带有包含行号的源代码引用 - **完整性**：枚举代码中所有可提取的单元，机械化地验证覆盖率 - **渐进式细化**：侦察 → 骨架 → 章节草稿 → 验证 → 对话式细化 - **可恢复性**：长时间的会话可以暂停和恢复 ## 设计渊源 `specback` 被定位为以下体系的最新一代： - **KDM (Knowledge Discovery Metamodel, ISO/IEC 19506:2012)**：语言无关的结构化知识表示 - **OMG ADM (Architecture-Driven Modernization)**：MDRE (Model-Driven Reverse Engineering，模型驱动逆向工程) - **Siala & Lano (2025)**：LLM × MDRE 的经验性整合研究 - **Reversa** (OSS)：“agent 可读的可执行规格说明书”的现代形式 - **IBM watsonx Code Assistant for Z / AWS Transform / CAST Imaging**：“确定性图 + LLM 自然语言”的混合架构 `specback` 在此基础上，将基于 skill 的 AI agent 功能（SKILL.md、subagents、AskUserQuestion、Task）最大化地整合到一个通用框架中。 ## 安装说明 ### 快速安装（推荐） 克隆此代码库，并从**项目根目录**（不在代码库内部）运行安装程序： ``` git clone https://github.com/nekolife1984/specback.git ./install.sh ``` 此交互式安装程序支持：Claude Code、Codex CLI、OpenCode、GitHub Copilot、Cursor 和其他 agent。 Windows 系统： ``` git clone https://github.com/nekolife1984/specback.git .\install.ps1 ``` 试运行模式： ``` ./install.sh --dry-run ``` 安装可选的 Python 依赖项（用于精确提取源代码的 tree-sitter 语法）： ``` ./install.sh --install-deps ``` ### 手动安装（示例） 推荐使用上述安装程序。如需手动安装，请将其复制到您的 agent 的 skill 目录中： ``` # 作为项目级技能（例如用于 Claude Code） mkdir -p .claude/skills/ cp -r skills/specback .claude/skills/ # 或作为用户级技能 mkdir -p ~/.claude/skills/ cp -r skills/specback ~/.claude/skills/ ``` ### 验证安装 启动您的 agent 并运行 `/help` —— `specback` 应该会出现在 skill 列表中。 ## 使用说明 ### 基本流程 ``` 1. Launch your coding agent at the target codebase root 2. Invoke the specback skill 3. Answer the 5-question goal definition (Phase 0) 4. Review recon results and pick a template (Phase 1) 5. Review the WBS and inventory (Phase 2) 6. Wait for parallel subagent investigation (Phase 3) 7. Review the verification report (Phase 4) 8. Refine the spec via Question Bank dialogue (Phase 5) 9. Receive the final deliverables (Phase 6) ``` ### 暂停与恢复 即使您中断了会话，进度也会保存到 `.specback/state.json` 中。在下次启动时，会出现一个恢复提示，并提供以下选项：继续 / 回滚 / 全部重置。 ### 输出位置 在目标项目的根目录下会创建一个 `.specback/` 目录，其中包含： ``` .specback/ ├── state.json # Progress tracking ├── goal.json # Phase 0 goal definition ├── recon-report.md # Phase 1 reconnaissance ├── source-map.json # Mechanical source unit map (v2) ├── inventory.json # All inventory items ├── trace.json # Spec-to-source traceability ├── wbs.json # Work breakdown ├── questions.json # Question Bank ├── knowledge-graph.jsonld # JSON-LD Knowledge Graph (machine-queryable) ├── drafts/ # Per-chapter drafts (intermediate, always in .specback/) └── final/ # Final deliverables (default) or {output_dir}/ if custom path set ``` 无论选择哪个输出目录，草稿始终保留在 `.specback/drafts/` 中。最终交付物将存放在 `{output_dir}/` 中（默认：`.specback/final/`；自定义：例如 `docs/specs/`）。 ## 语言 从 **v0.4.0** 开始，整个 skill 包（`SKILL.md`、`agents/`、`templates/`、`references/` 以及 `scripts/` 的 docstrings/messages）均以**英文为基础**。`goal.json.output_language` 的默认值为 `"en"`。 完全支持日文输出：在 Phase 0 Step 3 中选择 `日本語 (Japanese)`，agent 将动态地以日文渲染章节正文、AskUserQuestion 正文以及进度消息，同时将每一个机器可读的元素（`## Sources Read`、`[REF: ...]`、`[CONFIDENCE: ...]`、JSON keys、file slugs、ID prefixes）原样保留为英文。完整契约请参阅 SKILL.md 中的原则 #11。 ## 6+1 阶段状态机 | 阶段 | 名称 | 主要操作 | |-------|------|-------------| | 0 | Setup & Goal | 5 个问题的目标定义（范围、读者、粒度），输出语言 | | 1 | Recon & Template | 浅层侦察，模板选择，**depth mode 决策** | | 2 | Plan & WBS | 骨架生成，资产清单提取，WBS（根据 depth mode 分支） | | 3 | Investigate | 每章独立 sub-agent 调查（comprehensive：STEP A–G / outline：OUT-A–D） | | 4 | Verify | 覆盖率、完整性、11 项验证及循环修复 | | 5 | Refine via Dialogue | 3 阶段（概述 / 关键 cluster / 单独）对话以消除不确定性 | | 6 | Deliver | 将最终交付物输出到 `.specback/final/` | | **6.5** | **Interactive Deep-Dive** |（仅限 interactive 模式）根据用户引导按需生成深度分析章节 | 详情请见 [`skills/specback/SKILL.md`](skills/specback/SKILL.md)。 ## Depth 模式 在 Phase 1 结束时，可根据代码库规模和读者目的选择三种 depth 模式。 | 模式 | 使用场景 | 章节正文格式 | |------|----------|---------------------| | **`comprehensive`** | 审计 / 法规合规 —— 需要全覆盖 | 每个章节：200 行以上，10 个以上 `[REF:]` 标记，1 个以上 Mermaid 图表 | | **`outline`**（推荐默认值） | 通用，大型代码库 | Modules / Entities / Actions / Data / Dependencies 的枚举表格 + Mermaid + 深度分析候选列表 | | **`interactive`** | 团队参考，迭代细化 | 同 outline + Phase 6.5 接受用户主导的深度分析 | 对于 200 个文件及以下的代码库，会自动选择 `comprehensive` 模式。超过此阈值时，系统将提示用户进行选择。 在 `outline` / `interactive` 模式下，每个表格单元格都强制标记 **Confidence 标签**（🟢 VERIFIED / 🟡 INFERRED / 🔴 ASSUMED），以清晰区分猜测与已确认的事实。深度分析的候选项会根据 🔴 ASSUMED 的密度、前 10% 的复杂度以及业务关键关键词匹配（auth / payment / permission 等）进行自动筛选。 ## 支持的语言和典型单元 `references/inventory-units.md` 涵盖以下语言： - PHP（Laravel / Symfony / CakePHP 等） - COBOL（+ JCL） - Python（Django / Flask / FastAPI 等） - Java / Kotlin（Spring Boot 等） - JavaScript / TypeScript（Express / Next.js / NestJS / Expo / React Native / React 等） - C#（ASP.NET Core 等） - Go - **Ruby on Rails**：包含 14 个单元的目录，涵盖 Controller / Model / Concern / Service / Job / Mailer / Helper / Lib / Migration / Route / View / JS module / config / Mailer template `outline` 模式的概览表定义位于 `references/outline-tables.md` 中，提供了基于 ripgrep 的 6 种技术栈的穷举模式：Ruby/Rails、Python/Django、JS/TS/React、Go、Java/Kotlin (Spring Boot)。 针对主流框架提供了专门的提取指南： - **Flask**：Blueprints、view functions、hooks、Jinja2 templates、Flask-WTF forms、Flask-SQLAlchemy models、CLI commands - **FastAPI**：APIRouter、Pydantic schemas、Dependencies、Background tasks、Middleware、Exception handlers、Security schemes - **Next.js**（App Router / Pages Router）：page / route / layout / Server Action / Middleware，支持混合 router - **Expo / React Native**：Screens、Navigators、native modules、`app.json` / `eas.json`、permissions、Managed / Bare Workflow 检测 清单的**粒度规则**也已内置：最小计数（`max(50, file_count // 20)`）和宏单元比例上限由 Phase 4 的验证脚本强制执行。 ### 机械源码映射 v2（带角色类型） `scripts/source_map_v2/` 是一个具备框架感知能力、**基于 tree-sitter** 的提取器（schema 0.2.0），它将每个单元映射到五个通用表格（Modules / Entities / Actions / Data / Dependencies）并赋予其角色类型 —— `endpoint`（附带 HTTP method 和路径）、`model`、`schema`、`component`、`job`、`route_group`、`migration`、`datastore` 等 —— 横跨 **9 种语言**：Python、TypeScript/JavaScript、Ruby/Rails、PHP、Java、C#、Go、SQL、COBOL。通过框架检测（FastAPI / Django / Flask / Rails / Laravel / Spring / Next.js / Express / NestJS 等）来选择正确的单元类型。它与 v1 `source-map.py` 共存并且向后兼容。tree-sitter 是一个**可选**依赖项；没有对应语法的语言将回退为文件级单元，并发出醒目的警告（绝不静默丢弃）。单独运行： ``` python -m source_map_v2 --target --output .specback/source-map.json ``` 对于不支持的语言或框架，可通过 GitHub Issues 提出请求以进行添加。 ## 模板 包含初始的 4 个模板： - **Web Application Spec** (`templates/web-app.md`) - **Batch System Spec** (`templates/batch-system.md`) - **API Service Spec** (`templates/api-service.md`) - **Library/SDK Spec** (`templates/library-sdk.md`) 用户也可以自带模板。 ## 问题库 `specback` 将调查过程中产生的问题累积存储在 `.specback/questions.json` 中。 ### 7 个标准类别 1. **business_rule** 2. **architecture_decision** 3. **data_model_intent** 4. **external_integration** 5. **naming_history** 6. **operational_requirement** 7. **security_compliance** ### 严重程度 - **critical**：不解决此问题则无法编写章节 - **important**：可以通过猜测编写，但置信度较低 - **nice-to-have**：细节层面的完善 ### 无法回答的问题 那些永远得不到答案的问题（“SME 已经离职”、“没人记得历史背景”）会被标记为 `abandoned`，并明确记录在最终规格说明书的“未决事项”章节中。 这是规格说明书可信度的基石。 ## 目录结构 ``` specback/ ├── README.md ├── LICENSE ├── .gitignore └── skills/ └── specback/ ├── SKILL.md # Lightweight index (~90 lines) ├── phase-0-setup.md # Phase 0: Setup & Goal ├── phase-1-recon.md # Phase 1: Recon & Template ├── phase-2-wbs.md # Phase 2: Plan & WBS ├── phase-3-investigate.md # Phase 3: Investigate ├── phase-4-verify.md # Phase 4: Verify ├── phase-5-dialogue.md # Phase 5: Refine via Dialogue ├── phase-6-deliver.md # Phase 6: Deliver ├── phase-6-5-deepdive.md # Phase 6.5: Interactive Deep-Dive ├── phase-7-drift.md # Phase 7: Drift Detection ├── phase-7b-ref-autofix.md # Phase 7b: REF Auto-Fix ├── phase-7c-changespec.md # Phase 7c: ChangeSpec ├── question-bank.md # Question Bank operation ├── subagent-behavior.md # Sub-agent behaviour ├── state-management.md # State management & resume ├── agents/ │ └── chapter-investigator.md # Per-chapter sub-agent definition ├── references/ │ ├── inventory-units.md # Language units + granularity rules + Rails catalog │ ├── outline-tables.md # Overview-table definitions for outline mode (6 stacks) │ ├── template-catalog.md │ ├── question-categories.md │ ├── verification-checklists.md │ └── subagent-prompt.md ├── templates/ │ ├── web-app.md │ ├── batch-system.md │ ├── api-service.md │ └── library-sdk.md ├── variants/ │ └── B/ # Optional Context Optimization mode B │ ├── README.md # When and how to activate mode B │ ├── SKILL.phase3-stepG.md # Phase 3 STEP G override │ └── chapter-investigator.md # Mode-B sub-agent (return-value contract) └── scripts/ ├── source-map.py # Phase 2: source unit auto-extraction (v1) ├── source_map_v2/ # v2: role-typed, framework-aware, tree-sitter extractor (9 languages) │ ├── taxonomy.py # role vocabulary (5 universal tables) │ ├── model.py # source-map.json schema 0.2.0 │ ├── detect.py # framework detection (layer 1) │ ├── pipeline.py # 3-layer orchestrator │ ├── extractors/ # per-language extractors (layer 2) │ └── tests/ # acceptance tests ├── build-trace.py # End of Phase 3 / Phase 4: build trace.json from [REF:] markers ├── build-traceability.py # Phase 6: generate traceability.md └── coverage-check.py # Phase 4: multi-item verification (comprehensive / outline modes) ``` ## 状态 目前为 **v1.0.0** —— 首个稳定版本。 ### API 稳定性 以下内容被视为稳定的，在没有 MAJOR 版本更新的情况下不会更改： - **Pipeline phases**（Phase 1–7）及其输入/输出契约 - **`source_map_v2/` 输出 schemas**（`source-map.json`、`inventory.json`） ## 预印本 / 引用 此 skill 的设计原理、知识传承和实现决策详见以下预印本。在出版物或演讲中引用此工作时请予以引用。 ## 许可证 MIT License。详情请见 [LICENSE](LICENSE)。 ## 贡献 欢迎通过 GitHub Issues 提供反馈、模板请求和错误报告。 特别欢迎以下贡献： - 针对新语言/框架的清单单元定义 - 新模板（DWH、ML pipeline、IaC、移动端等） - 验证清单的补充 - 实际项目应用报告 ## 相关项目 - **cc-sdd**：Spec Driven Development。`specback` 的对应概念 - **Reversa**：具有 5 阶段 pipeline 的类似 OSS ## 致谢 该设计深受以下内容的启发： - 制定 KDM (ISO/IEC 19506:2012) 标准的 OMG 社区 - Reversa 的作者 sandeco - Siala & Lano (2025) 的“LLM4Models”论文 - Thoughtworks 关于 AI 生成规格说明书的评论文章 ## 文档 - [分支策略](docs/en/01-branching-strategy.md) # 日本語版 # specback — 逆向规格说明书生成器 📖 **英文版本位于顶部** — [跳转至英文版 →](#specback--reverse-spec-generator) `specback` 是一个通用框架，用于从遗留或现有代码库中自动生成面向维护工程师或最终客户的规格说明书。 它是执行“代码 → 规格”的 **逆向方向** 的 skill，定位为 `cc-sdd`（Spec Driven Development，规格驱动开发）的对立概念。 ## 开发初衷 遗留系统的现代化改造、新工程师熟悉代码库、交付规格文档、内部知识整合——在这些场景中，“我们有代码，但没有/无法信任规格说明书”的问题普遍存在。 进入 LLM 时代后，只需让 AI“根据这段代码生成规格说明书”，就能瞬间得到一份看似漂亮的规格说明书。然而在实际操作中，如果那份规格说明书是“充满猜测的完美虚构”，它就会在生产环境中失效。 `specback` 优先考虑以下几点。 - **诚实性**：不隐藏猜测的部分，明确标示出来。将“未决事项”作为独立章节列出 - **可追溯性**：所有的陈述都附带源代码的行号引用 - **防止遗漏**：枚举代码中所有可提取的单元，并机械化地验证覆盖率 - **渐进式细化**：遵循 侦察 → 骨架 → 章节草稿 → 验证 → 对话式细化 的步骤 - **可恢复性**：可以中断和恢复长时间的会话 ## 设计渊源 `specback` 的设计被定位为以下体系的最新一代。 - **KDM (Knowledge Discovery Metamodel, ISO/IEC 19506:2012)**：语言无关的中立结构化知识表示 - **OMG ADM (Architecture-Driven Modernization)**：MDRE (Model-Driven Reverse Engineering) - **Siala & Lano (2025)**：LLM × MDRE 的整合实证研究 - **Reversa** (OSS)：agent 可读的可执行规格说明书的现代形态 - **IBM watsonx Code Assistant for Z / AWS Transform / CAST Imaging**：“确定性图 + LLM 自然语言化”的混合架构 `specback` 总结了以上内容，是一个将基于 skill 的 AI agent 功能（SKILL.md、subagents、AskUserQuestion、Task）发挥到极致的框架。 ## 安装说明 ### 快速安装（推荐） ``` git clone https://github.com/nekolife1984/specback.git ./install.sh ``` 此交互式安装程序支持 Claude Code、Codex CLI、OpenCode、GitHub Copilot、Cursor 等多个 agent。 如果需要安装可选的 Python 依赖包（tree-sitter 各语言解析器）： ``` ./install.sh --install-deps ``` ### 手动部署（示例） 如果无法使用安装程序，请将其复制到您的 agent 的 skill 目录中： ``` # 例: Claude Code のプロジェクトレベルスキルとして mkdir -p .claude/skills/ cp -r skills/specback .claude/skills/ ``` ### 验证 启动 agent，如果在 `/help` 中的 skill 列表里显示了 `specback`，则说明安装成功。 ## 使用说明 ### 基本流程 ``` 1. 対象コードベースのルートでエージェントを起動 2. specback スキルを呼び出す 3. ゴール定義5問に回答(Phase 0) 4. 偵察結果を確認しテンプレート選定(Phase 1) 5. WBS と インベントリをレビュー(Phase 2) 6. サブエージェントによる並列調査を待つ(Phase 3) 7. 検証レポートを確認(Phase 4) 8. Question Bank の対話で仕様を精緻化(Phase 5) 9. 最終成果物を受け取る(Phase 6) ``` ### 暂停与恢复 即使中断了会话，进度也会保存在 `.specback/state.json` 中。下次启动 agent 时会显示恢复提示，您可以选择 从断点继续 / 回滚 / 全部重置。 ### 输出位置 在使用项目的根目录下会创建一个 `.specback/` 目录，并保存以下内容。 ``` .specback/ ├── state.json # 進捗管理 ├── goal.json # Phase 0 のゴール定義 ├── recon-report.md # Phase 1 の偵察結果 ├── source-map.json # 機械的なソースユニットマップ (v2) ├── inventory.json # 全インベントリ項目 ├── trace.json # 仕様とソースのトレーサビリティ ├── wbs.json # 作業分解 ├── questions.json # Question Bank ├── knowledge-graph.jsonld # JSON-LD 知識グラフ (機械クエリ可能) ├── drafts/ # 各章のドラフト（中間成果物、常に .specback/ 内） └── final/ # 最終成果物（デフォルト）／カスタムパス指定時は {output_dir}/ ``` Drafts（中间草稿）无论输出目标在哪里，都会始终放置在 `.specback/drafts/` 中。最终交付物将输出到 `{output_dir}/`（默认：`.specback/final/`，自定义示例：`docs/specs/`）。 ## 语言 从 **v0.4.0** 开始，skill 本体套件（`SKILL.md` / `agents/` / `templates/` / `references/` / `scripts/` 的 docstring 和消息）已转为**以英文为基础**。`goal.json.output_language` 的默认值为 `"en"`。 日文输出继续获得全面支持：在 Phase 0 Step 3 中选择 `日本語 (Japanese)`，章节正文、AskUserQuestion 问题文本、进度消息等自然语言输出将动态以日文生成。但是，机器可读元素（`## Sources Read`、`[REF: ...]`、`[CONFIDENCE: ...]`、JSON key、文件名 slug、ID prefix 等）无论何种语言均固定为英文。详情请参考 SKILL.md 的 Principle #11。 ## 6+1 阶段状态机 | 阶段 | 名称 | 主要操作 | |-------|------|---------| | 0 | Setup & Goal | 通过 5 个目标定义问题确定范围、读者、粒度，选择输出语言 | | 1 | Recon & Template | 进行浅层侦察，选择规格说明书模板，**判定 depth mode** | | 2 | Plan & WBS | 生成骨架，提取清单，划分 WBS（章节结构会根据 depth mode 产生分支） | | 3 | Investigate | 通过 sub-agent 独立调查各章节（comprehensive：STEP A〜G / outline：OUT-A〜D） | | 4 | Verify | 覆盖率、一致性、11 项验证及循环修复 | | 5 | Refine via Dialogue | 通过 3 个阶段（整体概貌/critical cluster/单独）的对话消除不确定性 | | 6 | Deliver | 将最终交付物输出至 `.specback/final/` | | **6.5** | **Interactive Deep-Dive** |（仅限 interactive 模式）根据用户的指令按需生成深度分析章节 | 详情请见 [`skills/specback/SKILL.md`](skills/specback/SKILL.md)。 ## Depth 模式 根据目标代码库的规模和读者用途，在 Phase 1 结束时从以下 3 种深度模式中进行选择。 | 模式 | 用途 | 章节正文的形式 | |-------|------|----------| | **`comprehensive`** | 需要完全覆盖的审计、合规性应对等情况 | 每个章节 200 行以上，`[REF:]` 10 个以上，Mermaid 1 个以上 | | **`outline`**（推荐默认值） | 一般用途、大规模代码库 | Modules / Entities / Actions / Data / Dependencies 的**概览表全枚举** + Mermaid + 深度分析候选列表 | | **`interactive`** | 团队持续参考，对话式细化 | 同 outline + 在 Phase 6.5 接受用户指令的深度分析 | 对于 200 个文件及以下的代码库，会自动选择 `comprehensive` 模式；超过 200 个文件时则会提示用户做出选择。 在 `outline` / `interactive` 模式下，每个表格单元格都必须附有 **Confidence 标签**（🟢 VERIFIED / 🟡 INFERRED / 🔴 ASSUMED），以明确区分猜测和已确认内容。深度分析候选对象会根据 🔴 ASSUMED 较多的行、复杂度排名前 10%、business-critical 关键词（auth / payment / permission 等）进行自动选定。 ## 支持的语言和典型单元 在 `references/inventory-units.md` 中涵盖了以下语言。 - PHP（Laravel / Symfony / CakePHP 等） - COBOL（+ JCL） - Python（Django / Flask / FastAPI 等） - Java / Kotlin（Spring Boot 等） - JavaScript / TypeScript（Express / Next.js / NestJS / Expo / React Native / React 等） - C#（ASP.NET Core 等） - Go - **Ruby on Rails**：涵盖 Controller / Model / Concern / Service / Job / Mailer / Helper / Lib / Migration / Route / View / JS module / config / Mailer template 的 14 个单元目录 `outline` 模式的概览表定义位于 `references/outline-tables.md`，针对 Ruby/Rails、Python/Django、JS/TS/React、Go、Java/Kotlin（Spring Boot）这 6 种语言，实现了“使用何种 ripgrep 模式进行全枚举”的机械化。 针对主要框架，我们提供了单独的提取指南。 - **Flask**：Blueprint、View function、Hook、Jinja2 template、Flask-WTF Form、Flask-SQLAlchemy Model、CLI command - **FastAPI**：APIRouter、Pydantic schema、Dependency、Background Task、Middleware、Exception handler、Security scheme - **Next.js**（App Router / Pages Router）：page / route / layout / Server Action / Middleware，支持两种 Router 混用 - **Expo / React Native**：Screen、Navigator、native module、`app.json` / `eas.json`、permission、Managed / Bare Workflow 识别 此外，还内置了清单的**粒度规定**，在 Phase 4 验证中会机械性地检查最低数量（`max(50, file_count // 20)`）和禁止的宏单元比例。 ### 机械源码映射 v2（带角色类型） `scripts/source_map_v2/` 是具备框架感知能力、**基于 tree-sitter** 的提取器（schema 0.2.0），它将所有单元映射到 5 个通用表格（Modules / Entities / Actions / Data / Dependencies），并赋予角色类型（`endpoint`〔附带 HTTP method+path〕 / `model` / `schema` / `component` / `job` / `route_group` / `migration` / `datastore` …）。支持 **9 种语言**：Python、TypeScript/JavaScript、Ruby/Rails、PHP、Java、C#、Go、SQL、COBOL。通过框架检测（FastAPI / Django / Flask / Rails / Laravel / Spring / Next.js / Express / NestJS …）来选择合适的单元类型。与 v1 `source-map.py` 并存且向后兼容。tree-sitter 是**可选依赖项**，对于没有语法的语言会回退为文件级单元 + 醒目的警告（绝不静默丢弃）。单独运行： ``` python -m source_map_v2 --target --output .specback/source-map.json ``` 不受支持的语言和框架会根据用户需求随时添加（通过 GitHub Issues）。 ## 模板 作为初始套件，附带了以下 4 种类型。 - **Web 应用程序规格说明书** (`templates/web-app.md`) - **批处理系统规格说明书** (`templates/batch-system.md`) - **API 服务规格说明书** (`templates/api-service.md`) - **Library/SDK 规格说明书** (`templates/library-sdk.md`) 用户也可以自带模板。 ## 问题库 `specback` 将调查过程中涌出的疑问结构化，并累积存储在 `.specback/questions.json` 中。 ### 7 个标准类别 1. **business_rule**（业务规则） 2. **architecture_decision**（架构决策） 3. **data_model_intent**（数据模型意图） 4. **external_integration**（外部系统集成） 5. **naming_history**（命名与历史背景） 6. **operational_requirement**（运维需求） 7. **security_compliance**（安全与合规） ### 严重程度 - **critical**：如果不消除这个疑问，就无法编写章节 - **important**：可以通过猜测编写，但置信度较低 - **nice-to-have**：涉及细节的完善 ### 无法回答的疑问 诸如“SME 已经离职”、“再也没人了解历史背景了”等永远得不到答案的疑问，会被标记为 `abandoned`，并明确记录在最终规格说明书的“未决事项”章节中。 这是保证规格说明书可靠性的根基。 ## 目录结构 ``` specback/ ├── README.md ├── LICENSE ├── .gitignore └── skills/ └── specback/ ├── SKILL.md # Lightweight index (~90 lines) ├── phase-0-setup.md # Phase 0: Setup & Goal ├── phase-1-recon.md # Phase 1: Recon & Template ├── phase-2-wbs.md # Phase 2: Plan & WBS ├── phase-3-investigate.md # Phase 3: Investigate ├── phase-4-verify.md # Phase 4: Verify ├── phase-5-dialogue.md # Phase 5: Refine via Dialogue ├── phase-6-deliver.md # Phase 6: Deliver ├── phase-6-5-deepdive.md # Phase 6.5: Interactive Deep-Dive ├── phase-7-drift.md # Phase 7: Drift Detection ├── phase-7b-ref-autofix.md # Phase 7b: REF Auto-Fix ├── phase-7c-changespec.md # Phase 7c: ChangeSpec ├── question-bank.md # Question Bank operation ├── subagent-behavior.md # Sub-agent behaviour ├── state-management.md # State management & resume ├── agents/ │ └── chapter-investigator.md # 章単位サブエージェント定義 ├── references/ │ ├── inventory-units.md # 言語別単位 + 粒度規定 + Rails カタログ │ ├── outline-tables.md # outline モード用の概観テーブル定義(6言語) │ ├── template-catalog.md │ ├── question-categories.md │ ├── verification-checklists.md │ └── subagent-prompt.md ├── templates/ │ ├── web-app.md │ ├── batch-system.md │ ├── api-service.md │ └── library-sdk.md ├── variants/ │ └── B/ # オプションの Context Optimization mode B │ ├── README.md # mode B の使いどころと活性化方法 │ ├── SKILL.phase3-stepG.md # Phase 3 STEP G の上書き │ └── chapter-investigator.md # mode B 用 sub-agent(return-value 契約) └── scripts/ ├── source-map.py # Phase 2: ソースユニット自動抽出 (v1) ├── source_map_v2/ # v2: 役割型付き・FW対応・tree-sitter 抽出器 (9言語) │ ├── taxonomy.py # 役割語彙 (5普遍テーブル) │ ├── model.py # source-map.json schema 0.2.0 │ ├── detect.py # フレームワーク検出 (第1層) │ ├── pipeline.py # 三層オーケストレータ │ ├── extractors/ # 言語別エクストラクタ (第2層) │ └── tests/ # 受け入れテスト ├── build-trace.py # Phase 3末/Phase 4: [REF:] からの trace.json 生成 ├── build-traceability.py # Phase 6: traceability.md 生成 └── coverage-check.py # Phase 4: 多項目検証(comprehensive / outline モード対応) ``` ## 出版与引用信息 本 skill 的设计理念、传承以及实现上的决策详见下方的预印本。如果您在论文或演讲中提及，请予以引用。 ## 许可证 MIT License。详情请参阅 [LICENSE](LICENSE)。 |## Contributing | |使用反馈、模板追加请求、Bug 报告请提交至 [GitHub Issues](https://github.com/nekolife1984/specback/issues)。 | |特别欢迎以下贡献。 | |- 新语言、框架的清单单元定义 |- 新模板（DWH、机器学习 pipeline、IaC、移动应用等） |- 验证检查清单的扩充 |- 实际项目适用案例的报告 | |关于分支策略和开发流程，请参考以下内容： | |- 英文版：[分支策略](docs/en/01-branching-strategy.md) |- 日文版：[分支策略](docs/ja/01-branching-strategy.md) ## 相关项目 - **cc-sdd**：Spec Driven Development（规格驱动开发）。`specback` 的对立概念 - **Reversa**：类似 OSS。5 阶段 pipeline ## 致谢 在设计理念方面，我们从以下的前期研究和实现中获得了巨大的启发。 - 制定 KDM（ISO/IEC 19506:2012）的 OMG 社区 - Reversa 的作者 sandeco 氏 - Siala & Lano (2025) 的“LLM4Models”论文 - Thoughtworks 关于 AI 规格说明书生成的评论文章

标签：AI智能体, LLM辅助, SOC Prime, 云资产清单, 代码分析, 凭证管理, 开发工具, 文档生成, 逆向工具, 逆向工程