困境

让 agent 改一个模块，信心满满地 accept。跑起来才发现：它用的是一个三个月前已经被重构掉的接口。你翻开代码仓库，发现那个接口的废弃决策其实写在某个 ADR 里，但 agent 根本没见过。

问题不在 agent 的能力，而在它的上下文。agent 做决策依赖项目级的上下文文档——AGENTS.md、设计决策记录、模块合约。但文档是人类写的，人类会忘记更新，于是文档就漂移了。决策过期了。目录级的 AGENTS.md 消失了。

Fractal Skills 是什么

Fractal Skills 是一套面向 coding agent 项目的文档编排技能组。它的核心思路很简单：软件是按层次组织的，上下文也应该按层次组织。

它定义了三层上下文协议：

你的项目不仅是代码的分层，决策记录、工程笔记、技术调研、复盘报告、任务规格都是 agent 做判断时需要的材料。Fractal Skills 用一个 docs/ 目录，给每一类文档划定了明确的 lane：

your-project/
└── docs/
    ├── decisions/        # 设计决策：当前真相，不是 ADR 坟场
    ├── engineering/      # 工程笔记：实现细节、性能数据、技术债务
    ├── research/         # 技术调研：探索、备选方案、实验记录
    ├── postmortem/       # 故障复盘：根因、修复、预防
    ├── specs/            # 任务规格：PRD → 可执行任务分组
    └── archive/          # 归档区：已废弃文档 + 墓碑标记

单一职责 skill, 可自由组合：

1. fractal-setup — 一键初始化 docs/ 文档骨架
2. fractal-audit — 巡检：哪些决策过期了、哪些 AGENTS.md 缺了、哪些 lane 错位了
3. fractal-agents-fill — 从代码里读出现状，自动补全缺失的合约
4. fractal-repo — 管理文档落点、命名规范、frontmatter 、生命周期
5. fractal-context — 当 header 语义漂移时，归一化 schema
6. decision-capture — 完整的决策生命周期：检查→创建→更新→取替→合并
7. to-task-specs — 把已解决的上下文生成可执行的任务文档
8. postmortem — 为 bug 和故障产出结构化的复盘记录

快速安装

npx skills add yaukwan/fractal-skills

🔗 仓库：github.com/yaukwan/fractal-skills