doc-gen
Skill13 starsChanged 3 months agoMITView on GitHub
从源码和现有文档生成面向测试的设计文档,补全知识库构建所需的输入
10 other projects use a version of this.
Adopted by
Most recently taken up by
- 5uck1ess/devkittheir own version, first seen Nov 15, 2026
- SethGammon/Citadeltheir own version, first seen Nov 4, 2026
- allysgrandiose674/Armorytheir own version, first seen Oct 13, 2026
- mayankjain1815-commits/CITADELtheir own version, first seen Oct 13, 2026
- neronain/ClaudeSkills-Neronaintheir own version, first seen Aug 9, 2026
- jpoindexter/theft-kittheir own version, first seen May 20, 2026
Used with
Projects with it also use ascii-diagram, research-fleet and 9 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
SethGammonSkillascii-diagram
Generate perfectly aligned ASCII diagrams — architecture, flow, sequence, box-and-arrow. Uses a programmatic character-grid approach so alignment is guaranteed by math, not token prediction. Includes post-render verification.
Also in 4 projects that use this
SethGammonSkillresearch-fleet
Parallel research using Fleet wave mechanics. Spawns multiple scout agents, each investigating a different angle of the same question. Findings are compressed between waves. Produces a unified research brief from multiple independent perspectives.
Also in 3 projects that use this
vicoa-aiSkilllive-preview
Start a local app in the current user project, expose it through a tunnel, and return preview details in structured Markdown. Use when the user asks for a preview URL, public URL, shareable localhost, mobile/web preview, or tunnel setup.
Also in 4 projects that use this
chidekinaSkilltest-gen
Generate test cases from type constraints and specs. Creates boundary tests, edge cases, and fixtures automatically. Pact-lang inspired. Triggers on: generate tests, test from spec, create fixtures, boundary tests.
Also in 6 projects that use this
BerryKuipersSkillscaffold
Detect project stack, apply architecture patterns, wire quality gates, and scaffold features. Use when bootstrapping a project, adding a vertical slice, wiring CI/CD, adding Docker compose, or setting up quality gates.
Also in 4 projects that use this
wpankSkillsession-handoff
WHAT: Create comprehensive handoff documents that enable fresh AI agents to seamlessly continue work with zero ambiguity. Solves long-running agent context exhaustion problem.
Also in 4 projects that use this
- +1 more from SethGammon
Other versions10 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 10
- SethGammon/Citadel★ 927same name
- SethGammon/Armory★ 19same name
- botlearn-ai/botlearn-skills★ 9same name
- 5uck1ess/devkit★ 4same name
- mayankjain1815-commits/CITADEL★ 4same name
- neronain/ClaudeSkills-Neronain★ 3same name
- CodeWithBehnam/cc-docs★ 2same name
- allysgrandiose674/Armory★ 1same name
- jpoindexter/theft-kit★ 1same name
- 354685856-sn/claude-code-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository21 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- case-migrateSkill
- doc-reviewSkill
- emitter-buildSkill
- knowledge-buildSkill
- test-codegenSkill
- test-designSkill
- test-fixSkill
- test-maintainSkill
- test-scaffoldSkill
- case-migrateSkill
- doc-genSkill
- doc-reviewSkill
- emitter-buildSkill
- knowledge-buildSkill
- test-codegenSkill
- test-designSkill
- test-fixSkill
- test-maintainSkill
- test-scaffoldSkill
The file
Files
设计文档生成
从 $source_dir 的源码和 $doc_dir 的现有文档中提取设计信息,生成面向测试的设计文档,输出到 $output_dir。$doc_dir 未提供时只从源码和公开接口定义提取。
当 $module_filter 非空时(逗号分隔),仅分析指定模块。
参考文档
四种输出文档的完整模板拆分到:
refs/templates.md— overview.md、module<name>.md、_data_flow.md、_discrepancies.md 的结构模板和行数限制
你的角色
你是一个资深开发,需要为测试团队编写设计文档。你读代码提取系统行为,结合现有文档交叉验证,产出的文档将作为测试知识库构建的输入。
信息来源优先级
- API 定义(
.proto、路由文件、OpenAPI spec)— 外部契约,最可靠 - 配置文件(
.yaml、.json)+ 配置加载代码 — 系统参数全集 - 入口文件(
main.py、app.py)— 组件依赖和启动流程 - 业务代码(
.py服务文件)— 业务规则和错误处理 - 数据文件(
.tsv、.csv表头)— 数据格式 - 现有文档(
$doc_dir)— 交叉验证和补充
代码阅读策略
签名优先,按需深入:
- 第一遍只读:类名、方法签名(参数+返回值)、docstring、常量/枚举、import
- 需要深入读实现的场景:条件分支(业务规则)、try/except(错误处理)、外部调用(依赖)、logging 语句(可观测性)
- 不读:测试文件、迁移脚本、构建工具、注释中的 TODO
上下文控制:
- 单文件超过 300 行时,先读签名索引,再按需读具体方法
$module_filter非空时,跳过无关模块的深度分析- 工具/辅助方法只读签名,不读实现
执行流程
第一步:结构侦察
- Glob 扫描
$source_dir,按类型分类文件:- 入口文件(main.py、app.py、main.py)
- API 定义(.proto、_app.py、routes/、openapi.)
- 配置(.yaml、.json、.toml)
- 数据文件(.tsv、.csv)
- 业务代码(.py,排除 test_*、tests/)
- 读取入口文件 → 识别组件列表和依赖关系
- 读取 API 定义 → 提取完整接口契约
- 读取配置文件 + 配置加载代码 → 提取所有配置项(名称、类型、默认值)
- 读取各业务模块的签名索引(类名、方法签名、常量、枚举)
- 如果
$module_filter非空,确定目标模块对应的源文件
第二步:文档盘点
仅当 $doc_dir 非空时执行。
- 读取
$doc_dir下所有文档 - 分类:系统总览 / 迭代变更 / 接入指南 / 技术规格 / 其他
- 建立覆盖地图:每个模块是否有文档覆盖、覆盖了哪些方面
第三步:逐模块深度分析
对每个模块(受 $module_filter 约束):
- 有文档覆盖:先读文档摘要,带着文档描述去读代码验证
- 无文档覆盖:直接读代码实现
从代码中提取:
- 输入/输出的完整字段定义(类型、必填、默认值、取值范围)
- 条件分支 → 业务规则(含数值边界,明确包含/不包含)
- try/except + 错误返回 → 错误场景(触发条件、错误码、是否降级)
- 外部调用(Redis/gRPC/HTTP)→ 依赖说明(协议、超时、不可用时行为)
- logging 语句 → 可观测性(级别、内容、触发条件)
- 硬编码常量 → 标注为潜在配置缺失
- 已定义但未使用的错误码/常量
第四步:端到端数据流追踪
- 从主编排方法出发,按执行顺序追踪
- 记录每步:输入数据结构 → 变换逻辑 → 输出数据结构 → 异常分支
- 关注模块间数据传递时的格式转换、字段丢失、类型变化
第五步:交叉比对
仅当 $doc_dir 非空时执行。
逐模块比对文档描述与代码实际行为,记录三类差异:
- 文档有、代码无:可能是计划中未实现的功能
- 代码有、文档无:未文档化的行为,测试盲区
- 描述不一致:最危险,可能导致测试基于错误假设
同时检查:已定义但未使用的错误码、常量、配置项。
第六步:生成文档
按 refs/templates.md 中的模板结构输出到 $output_dir:
$output_dir/
├── _overview.md # 系统概述
├── _data_flow.md # 端到端数据流
├── module_<name>.md # 每模块一个
└── _discrepancies.md # 差异报告(仅当有 $doc_dir)生成完毕后输出摘要。
来源标注
每条业务规则和错误场景必须标注来源:
[代码]— 仅从代码提取,文档未覆盖[文档]— 文档有描述且代码一致[差异]— 代码行为与文档描述不一致
无 $doc_dir 时,所有信息标注 [代码]。
质量约束
- 不猜测意图:只描述代码实际做了什么。看不懂的标注
[?实现意图不明: ...] - 精确到可测试:每条业务规则必须精确到可写测试断言,含数值边界和包含/不包含
- 主体不含源码细节:函数名、行号统一放「实现参考」section,主体只描述行为
- 行数控制:overview ≤ 150,模块 ≤ 300,数据流 ≤ 200,差异 ≤ 200
- 增量友好:
$module_filter指定时只生成/更新指定模块文档,不动其他文件 - 错误码完整性:列出所有已定义错误码,标注哪些实际使用、哪些未使用
完成后输出
## 设计文档生成摘要
源码目录:$source_dir
文档目录:$doc_dir(无则标注"未提供")
输出目录:$output_dir
模块过滤:$module_filter(无则标注"全量")
### 生成文件
| 文件 | 行数 | 覆盖模块 |
### 模块覆盖
| 模块 | 代码已分析 | 文档已覆盖 | 差异数 |
### 关键发现
- 文档未覆盖的模块:...
- 代码与文档不一致:...
- 已定义未使用的错误码/配置:...
### 建议
(对后续知识库构建的建议:哪些模块文档质量足够,哪些需人工补充)Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

