docstrata

English | 中文

按知识性质分层，为任意项目生成和维护文档。Agent Skill，兼容 Claude Code、Cursor 等主流工具。

定位

• 分层生成：prd（产品主张）/ requirements（需求决策）/ knowledge（领域材料）/ wiki（业务全景）/ dev（开发结论）
• 开箱即用：一条命令，工具自行探索项目，只在信息有缺口时提问
• 增量更新：已有文档则 diff 更新，保留人工修改，不覆盖
• 收缩维护：compact 把随迭代膨胀的层收回有界，长期记忆不腐化
• 兼容主流：Claude Code、Cursor、Gemini CLI、Codex、OpenCode 等 Agent Skills 标准工具

背景

人与 agent 结对编程的综合效率依然最高。 工具的意义是提速这个小闭环：让人说清需求、做出决策，agent 专注执行，各司其职。但现有工具各有短板：

• spec 框架（speckit、BMAD、Superpower 等）：把需求分析、任务规划、代码生成全部编排进来，追求一键全自动。框架本身过重，理解和上手成本高；大型任务跑半小时出来的不是想要的结果，沉没成本大；小型任务准备一堆文档，负担大于收益。
• plan 模式：处理"这次任务怎么做"，执行规划会话内有效。细化过多会约束 agent 的发挥，且决策留在会话里，下次从头来过。
• grill-with-docs（Matt Pocock）：对照已有领域模型逐一审问计划，澄清术语、记录决策，跨会话持久有效。但信息管理散，没有区分谁看什么、什么性质的内容放哪里。

docstrata 在 grill-with-docs 的基础上，把信息按性质分层管理，让文档对人、对 agent 都有独立的阅读和检索价值。框架只做该做的事：澄清需求、记录决策，其他交给模型。

为什么要分层

项目文档服务三类读者：开发者、业务管理侧、coding agent。三者对文档的形式需求完全不同，却往往被混进同一份 README，或根本没有对应的地方存放：

这四类知识的信息性质不同，混在一起写会相互污染。典型的漂移场景：requirements 和 dev 混写后，新的 agent 会话会把已确定的架构决策当作开放问题重新讨论，无谓地重跑 grill，甚至推翻之前的结论。分层解决的正是这个问题。

CoALA（Sumers et al., Princeton/CMU, TMLR 2024）研究 AI agent 长期记忆架构，把长期记忆分成三类，为四层划分提供了理论依据：

prd 层是这之上的前瞻产品意图（要做成什么），不属 CoALA 记忆三类，是当下主张——区别于 requirements 记录的已发生事实。

INDEX.md 是各层的检索入口，服务 coding agent 的 working memory 装填，本身不是那一层。

和 AGENTS.md 的区别

AGENTS.md / CLAUDE.md 的定位是行为约束：告诉 agent 每次该怎么干活，每次会话全量加载，每次都消耗 context token。

docstrata 产出的是知识层：通过 INDEX.md 按需加载，用到哪层读哪层，不用的不付 token。两者不是替代关系：行为约束仍然需要，docstrata 做的是行为约束之外的知识沉淀。把所有内容塞进 AGENTS.md 既难维护，也意味着每次会话都为用不到的内容付出 context 代价。

怎么运作

每层走同一个五步循环：

GRILL 的核心逻辑：每层预先声明一份信息维度集合（completeness contract），缺口决定问什么：

问题 = 契约维度 − 已探索到的信息

有完整需求文档和开发日志的项目，GRILL 往往整层跳过。提问模式来自 grill-with-docs（Matt Pocock）。

生成时内建信息批判，处理多源信息的质量问题：

• 来源排序：运行代码 > 测试 > git 历史 > 文档；多源矛盾不静默选一个
• 认知标注：事实与推断分开标，标注格式 [事实] / [推断] / [待确认]
• LLM 偏向：遇到非标实现，记录项目实际行为，不"纠正"成标准做法

长期迭代下层文档会膨胀，compact 手动收缩（先压：丢 code/git 可复原项 + 去重 + 按主题归并；再拆；归档不删、硬事实逐字保真），是生成之外的维护操作。

生成的文件固定放在 docs/，随 git 提交：

docs/
├── prd.md                # 产品主张（前瞻 intent，对内）
├── wiki.md
├── requirements.md
├── knowledge/
│   ├── knowledge.md      # 整理后的索引
│   └── raw/              # 原始材料（不改动）
├── dev.md
└── INDEX.md              # coding agent 的检索入口

安装

npx skills add linhai0872/docstrata

兼容支持 Agent Skills 标准 的工具：Claude Code、Cursor、Gemini CLI、Codex、OpenCode 等。

使用

/docstrata prd             # 产品主张 → docs/prd.md
/docstrata requirements    # 需求共识 → docs/requirements.md
/docstrata knowledge       # 业务材料索引 → docs/knowledge/knowledge.md
/docstrata wiki            # 业务全景 → docs/wiki.md
/docstrata dev             # 开发结论 → docs/dev.md
/docstrata index           # coding agent 检索入口 → docs/INDEX.md
/docstrata compact         # 收缩膨胀的层（可带层名，如 /docstrata compact dev）
/docstrata all             # 按依赖顺序全部生成

支持任意项目类型，工具自行判断，无需声明。/docstrata all 会跳过无实质价值的层：没有业务材料就跳过 knowledge，功能一目了然的小项目 requirements 也可以不单独成文。

评测

改了 skill 之后，怎么知道文档质量有没有真的变好？靠主观感觉容易自欺欺人。eval/ 让 LLM 替你读生成的文档、按固定标准打分——改前改后各跑一次，对比分数，是真改进还是噪声一目了然。

流程：改某层生成规范 → 对测试项目重新生成文档 → 打分 → 与上一轮对比。

打分分三档，按需选用：

打分标准：文档覆不覆盖该层的核心维度、有没有把推断误标成事实、受众是否适配等，共 5 项，每项 0–3 分，归一化后 ≥ 0.7 算通过。

docstrata 用自身文档作为测试案例——先用工具生成，再用 eval 打分，自己验自己。详见 eval/README.md。

设计文档

本项目的文档用自身的分层结构写成：