brain-to-docs 实战指南用结构化访谈把项目愿景与决策沉淀为 README 与 ADR 文档【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills导读本文围绕 AASagentic-awesome-skills插件仓库中的brain-to-docs技能展开讲解如何通过一问一答的访谈式对话把用户脑中的项目愿景、品味、判断、知识与决策系统地萃取出来写入清晰简洁的 Markdown 文档README 承载愿景docs/adr/承载决策。读完本文你将掌握 brain-to-docs 的核心循环、提问策略、更新规则与 ADR 书写规范并了解它与仓库内architecture-decision-records技能的配合方式能够把一段漫谈式讨论转化为可持续维护的项目文档资产。技能定位为什么需要“大脑转文档”brain-to-docs 的全部意义在于尽可能多地把用户的品味、判断、知识、愿景、偏好与决策萃取成文字保存为项目内清晰、简洁的 Markdown 文档。其定位在技能元信息中写得非常直白name: brain-to-docs description: Interview the user to turn project vision and decisions into README and ADR documentation. category: productivity risk: critical source: community tags: [documentation, adr, planning] tools: [claude, codex] license: MIT它属于productivity生产力类别风险等级被标记为critical因为它涉及频繁写文件README 与 ADR属于会改动仓库状态的操作。该技能面向 Claude 与 Codex 两类 Agent来源为社区贡献davidondrej/skills并在 AAS 中被收录、适配。它要解决的核心问题很实际大多数项目的“隐性知识”都存在于开发者脑中——为什么选这个数据库、为什么拒绝某个方案、产品愿景是什么。这些知识一旦不落盘就会随人员流动而流失而直接让用户写文档又往往缺乏动力与结构。brain-to-docs 用访谈的方式让沉淀文档这件事变得低成本、可持续。何时使用适用场景与判断标准技能的When to Use章节给出了两条明确的使用触发条件用户希望把项目的愿景vision、决策decisions或偏好preferences萃取为可持久化的文档README 与 ADR 应当通过一来一回的访谈式对话来构建。与之形成对照的是仓库中同类的architecture-decision-records技能它给出了更细化的“该写 / 不写”判断表可作为何时使用 ADR 的补充依据写 ADR跳过 ADR采用新框架小版本升级数据库技术选型Bug 修复API 设计模式实现细节安全架构日常维护集成模式配置变更简言之涉及架构级、不可逆或影响面大的决策时应写 ADR小修小补、例行维护则不必。brain-to-docs 的价值正是在这个判断基础上主动把访谈推进到这些“值得落盘”的话题上。核心工作循环四个不可跳过的步骤brain-to-docs 的灵魂是它的主循环原文规定了四个步骤每一步都有强制约束1. 每次先读文档无条件Check docs first, every time. Readdocs/adr/(andREADME.md) before doing anything — other agents and people add/edit ADRs constantly.在开始任何动作之前必须先读取docs/adr/与README.md。原因是多人/多 Agent 协作环境下其他人随时可能在新增或编辑 ADR。只有先掌握已有文档才能避免重复提问、避免与既有决策冲突、也才能让后续更新是“增量式”的而不是“覆盖式”的。2. 每次提问 5 个不同问题纯文本形式数量默认 5 个问题除非用户要求不同数量形式必须用纯文本提问绝不使用问题 UIquestions UI多样性要求问题必须高度多样覆盖宽泛、有创造性的独特视角而不是全部同类例如不要全是“技术栈”、全是“产品”或全是“变现”。例外是用户明确指定聚焦领域时按用户要求执行作答自由用户只需回答自己觉得最有用的那些问题即可。这条规则的设计意图很明确5 个高多样性问题比 5 个同质问题更能触发用户从不同维度思考项目从而挖出更多隐性决策与偏好。3. 每次回答后立即更新文档无例外Update docs after EVERY answer — no exceptions.用户每回答一个问题就必须立刻判断该内容应写入README.md还是新建一个 ADR并立即更新。判断依据是内容性质愿景类内容进 README决策类内容进 ADR。不允许攒着几个回答最后一次性写文档——即时落盘才能保证信息不丢失、也才能让后续提问建立在新文档之上。4. 循环直到用户喊停重复上述过程直到用户说出“were done”或类似表述为止。整个访谈没有固定轮数上限以用户意愿为终止信号。规则简洁、编号、不挑战技能在Rules章节给出了三条硬性约束它们是整个流程的书写与沟通基调全程极简所有回答与响应必须非常简洁VERY CONCISE句子要短SHORT全部使用简明英语PLAIN ENGLISH。这保证了访谈节奏轻快不喧宾夺主ADR 格式固定ADR 必须是短小、带编号的NNNN-slug.md文件结构为 Status Context Decision ConsequencesREADME 只放愿景README 只承载愿景决策一律进 ADR两者职责严格分离不主动挑战用户除非用户主动要求或用户正在犯严重错误否则不要质疑用户的思考。ADR 写法详解从四段式到五类模板brain-to-docs 规定 ADR 采用NNNN-slug.md命名、含 Status/Context/Decision/Consequences 四段式结构。仓库中的architecture-decision-records技能对这一规范做了大幅扩充提供五种可直接套用的模板可作为 brain-to-docs 访谈落盘时的格式参考标准 MADR 格式最完整适用于重大决策包含 Status、Context、Decision Drivers、Considered Options、Decision、Rationale、ConsequencesPositive/Negative/Risks、Implementation Notes、Related Decisions、References 等完整小节。核心三要素Context上下文我们为什么需要做这个决策Decision决策我们决定了什么Consequences后果决策带来什么结果。轻量 ADRLightweight适用于小范围但仍有记录价值的决策用**Status**、**Date**、**Deciders**加粗字段替代完整小节正文只需 Context / Decision / Consequences 三部分并把 Consequences 拆为 Good / Bad / Mitigations。Y-Statement 格式一句话决策用固定句式一句话讲清决策全貌适合作为超轻量记录In the context of..., facing..., we decided for...and against..., to achieve..., accepting that...。弃用类 ADRDeprecation专门记录“推翻旧决策”的场景在 Status 中标注Accepted (Supersedes ADR-xxxx)并补充 Migration Plan 与 Lessons Learned。RFC 风格面向仍处于讨论期的大方案包含 Summary、Motivation、Detailed Design、Drawbacks、Alternatives、Unresolved Questions、Implementation Plan。ADR 目录组织与索引维护brain-to-docs 要求决策落入docs/adr/仓库中 ADR 技能给出了标准目录结构docs/ ├── adr/ │ ├── README.md # Index and guidelines │ ├── template.md # Teams ADR template │ ├── 0001-use-postgresql.md │ ├── 0002-caching-strategy.md │ ├── 0003-mongodb-user-profiles.md # [DEPRECATED] │ └── 0020-deprecate-mongodb.md # Supersedes 0003docs/adr/README.md作为索引以表格形式记录每个 ADR 的编号、标题、状态与日期并在“Creating a New ADR”中约定流程复制template.md为NNNN-title-with-dashes.md→ 填充模板 → 提交 PR 评审 → 通过后更新索引。ADR 生命周期为Proposed → Accepted → Deprecated → Superseded ↓ Rejected在访谈中产生的新决策应随时以Proposed状态落盘再经由评审推进到Accepted。访谈场景示例技能原文给出一个最小示例用户请求Extract project vision, decisions, or preferences into durable docs.Agent 随即进入主循环先读README.md与docs/adr/然后抛出 5 个高多样性问题例如分别覆盖产品定位、目标用户、技术约束、变现方式、团队偏好等不同维度用户挑选回答每答一个就即时更新 README 或新建 ADR直到用户说“were done”。最佳实践让访谈产出的文档长期有价值结合 ADR 技能中的 Best Practices 章节brain-to-docs 访谈产出的文档应遵循以下原则应当做Dos早写 ADR——在实现开始之前记录保持短小——每份 ADR 控制在 1–2 页以内诚实记录权衡——真实写出缺点链接相关决策——逐步构建决策图decision graph及时更新状态——被取代时标记 Deprecated/Superseded。不要做Donts不要修改已接受的 ADR——应新写一份来取代它不要省略 Context——未来的读者需要背景不要隐藏失败——被拒绝的决策同样有价值不要含糊——具体的决策配具体的后果不要止步于文档——没有行动的 ADR 是浪费。局限性与安全边界技能在Limitations中明确了两点约束来源适配提示本技能改编自davidondrej/skills在使用前应核对本地路径、工具、凭据与 Agent 特性verify local paths, tools, credentials, and agent features before acting操作需审批涉及命令执行、远程访问、定时任务、浏览器自动化或文件变更类工作流时必须先获得用户明确批准并确认目标环境get explicit user approval and confirm the target environment first。这一点与技能的risk: critical元信息呼应brain-to-docs 会高频写入 README 与 ADR 文件属于对仓库有实际改动能力的技能因此必须在用户批准的前提下、针对明确的目标环境执行。小结brain-to-docs 提供了一套完整的“隐性知识显性化”工作流先读文档 → 5 个高多样性问题 → 每答必更 → 循环至用户叫停。配合仓库中architecture-decision-records技能的 ADR 模板、目录规范与评审清单可以让一个项目的愿景README与决策docs/adr/在轻量访谈中持续沉淀形成团队与 Agent 都可依赖的决策资产。延伸阅读本文主文档plugins/agentic-awesome-skills-claude/skills/brain-to-docs/SKILL.mdADR 模板与最佳实践plugins/agentic-awesome-skills/skills/architecture-decision-records/SKILL.mdAAS 技能解剖规范了解 SKILL.md 结构约定docs/SKILL_ANATOMY.md【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考