compound-docs

compound-docs

流程

单文件架构——每个问题在其症状类别目录中对应一个 Markdown 文件（例如，docs/solutions/performance-issues/n-plus-one-briefs.md），并使用 YAML frontmatter 存储元数据。

遵循 7 步文档记录流程。完整详情请参阅 documentation-process.md。

1. 检测确认——在用户说“这次好了”“已经修复”等内容后自动调用。跳过琐碎修复。
2. 收集上下文——提取模块、症状、调查尝试、根本原因、解决方案和预防措施。若缺少关键信息则阻止继续。
3. 检查现有文档——搜索 docs/solutions/ 中的类似问题。如果找到，提供以下选项：创建带交叉引用的新文档、更新现有文档，或选择其他方案。
4. 生成文件名——格式：[sanitized-symptom]-[module]-[YYYYMMDD].md
5. 验证 YAML——将草稿保存到临时 Markdown 文件，然后对其运行 validate-frontmatter.sh。验证器需要 Python 3 和 PyYAML；如果缺少依赖项，应如实说明，不要声称已完成验证。如果无效，请修复 frontmatter 并重新运行，直到通过。
6. 创建文档——使用 resolution-template.md，将文件写入 docs/solutions/[category]/[filename].md。
7. 添加交叉引用——链接相关问题。检测关键模式（3 个或更多类似问题）。

记录门槛（第 1 步）： 只有在没有这份文档的情况下，未来的工程师阅读最终代码、测试、注释、CLAUDE.md/AGENTS.md 以及现有文档或技能后，仍会重蹈覆辙或重复调查时，才记录。若其中任何一项已包含相关经验，则跳过。

---

决策菜单

成功记录文档后，通过 AskUserQuestion（Claude Code；如果尚未加载，则使用 ToolSearch select:AskUserQuestion 加载）或 request_user_input（Codex）展示以下选项；如果无法使用，则在聊天中显示带编号的菜单，并等待用户回复：

Solution documented

File created:
- docs/solutions/[category]/[filename].md

What's next?
1. Continue workflow (recommended)
2. Add to Required Reading - Promote to critical patterns
3. Link related issues - Connect to similar problems
4. Add to existing skill - Add to a learning skill
5. Create new skill - Extract into new learning skill
6. View documentation - See what was captured
7. Other

有关如何详细处理回复，请参阅 documentation-process.md。

---

成功标准

• YAML frontmatter 已验证（所有必填字段和格式均正确）
• 文件已创建在 docs/solutions/[category]/[filename].md
• 枚举值与架构完全一致
• 解决方案部分包含代码示例
• 如果找到相关问题，已添加交叉引用
• 已向用户展示决策菜单并确认操作

---

参考资料

• documentation-process.md - 完整的 7 步流程及验证门槛
• yaml-schema.md - YAML frontmatter 架构和枚举值
• quality-guidelines.md - 质量标准、执行规则和错误处理
• example-scenario.md - 记录 N+1 查询修复的完整演示
• resolution-template.md - 文档文件模板
• critical-pattern-template.md - 关键模式条目模板
• validate-frontmatter.sh - 根据架构验证 YAML frontmatter
• validate-frontmatter.py - 安全的 YAML 解析器和字段验证；获得授权后，可使用 python3 -m pip install PyYAML 安装其依赖项

集成

• 过时经验审查（Claude Code 中的 /ia-compound-refresh）——检查 docs/solutions/ 中已过时的条目