1741505640/capmap-skills

capmap-skills

Vibe Coding 时代的能力底图策展套件：把「方案 → 开发 → 测试 → 落地 → 归档」做成可复用的 Agent Skills 闭环，并用 Obsidian 把方案关系画成图谱。

核心理念：代码给 Agent 看，文档给人看——人靠可读的方案与底图理解系统；Agent 靠契约化文档与状态机把开发节奏跑完整。

为什么需要

高频用 AI 写代码时，几组矛盾会同时出现：

| 矛盾 | 表现 |
|------|------|
| 感知下降 | 改动很快，人对模块边界、函数意图的掌握变浅，Review 变难 |
| 方案膨胀 | 每次开发都会产出 Plan / 方案；文档越来越多，难检索、难淘汰 |
| 关联断裂 | 方案与真实代码路径、git 合入历史弱关联 |
| 关系隐形 | 方案之间的依赖、替代、分叉，散落 Markdown 里看不出来 |

capmap-skills 的解法：

1. 人读文档：方案写清决策与变更；能力底图写清「有什么能力、代码在哪、怎么用」
2. Agent 跟契约：按阶段 Skill 推进，状态不可跳步，改完可 lint
3. 图谱给人导航：以 docs_root 为 Obsidian Vault，用唯一文件名 [[wikilink]] 连成图（init 预置状态颜色组）

能做什么

| 能力 | 说明 |
|------|------|
| 初始化 | 选定任意名的 docs_root，建骨架（含 项目全貌.md 人读导读）、写 capmap.yaml，写入 Obsidian graph.json 颜色组 |
| 写方案 | 进行中方案带 ## 变更记录 |
| 开发收尾 | 对照方案判定完成后更新底图 §1/§2，方案标「已开发」，并询问是否转测试（≠ 已验证 / 已落地） |
| 测试 / 规范 | 测试进 测试/，长期用法进 规范/，再谈落地 |
| 反补 / 归档 | git 反补底图 §4；闭环方案进 _archive（不留 stub） |
| 校验 | capmap-lint 查断链、状态跳步等；skill 内含 GitHub action.yml |

闭环

方案（决策+体量）  capmap-scheme
│
├─【小】────────────────────────────┐
└─【大】spec → slice → gate（点名）──┤
↓
开发收尾              capmap-dev
↓
测试 / 规范 / 归档    capmap-test → norm → archive
↑
反补                  capmap-backfill

方案主状态（禁止跳步；大需求多 规格中→已拆分）：

小：方案中 → 已确认 → 开发中 → 已开发 → 验证中 → 已验证 → 落地中 → 已落地 → 已归档
大：方案中 → 已确认 → 规格中 → 已拆分 → 开发中 → 已开发 → …（同上）

套件

| Skill | 用途 |
|-------|------|
| capmap-system | 总入口、硬规则、契约 reference |
| capmap-init | docs_root、骨架、capmap.yaml、Obsidian 颜色组 |
| capmap-scheme | 写/改方案；升已确认时体量判断+询问 |
| capmap-spec | 大需求：执行规格 |
| capmap-slice | 大需求：垂直切片 DAG；推荐运行模式后停住 |
| capmap-gate | 大需求：frontier / 点名开干 / 交票验收 |
| capmap-dev | 对照方案判定完成后更新底图（大：须切片全验收）；标完询问是否转测试 |
| capmap-test | 测试计划与记录（用户确认转测后拍 1；拍 2 人测/免测 → 已验证） |
| capmap-norm | 长期使用 / 配置规范 |
| capmap-backfill | 从 git 反补底图 §4 |
| capmap-archive | 方案归档 |
| capmap-lint | 结构校验 + action.yml |
| capmap-debug | 运行时修锅回合：复现/假设/停损；不进状态机 |

契约细节：skills/capmap-system/reference/。

安装

本套件只发布 skills/capmap-。权威落点是业务仓的 .agents/skills/（capmap.yaml 与 lint 路径都按此约定）。

装完后目标布局：

your-repo/
.agents/skills/capmap-/                 ← 本仓 skills/ 下全部目录
.agents/skills/capmap-system/capmap.yaml ← 由 capmap-init 生成
/                             ← 任意名；init 时选定

推荐：npx skills

在业务仓根目录：

npx skills add 1741505640/capmap-skills --skill '' -y

指定 Agent（可多选）
npx skills add 1741505640/capmap-skills --agent cursor codex claude-code --skill '' -y

检测到的全部 Agent
npx skills add 1741505640/capmap-skills --agent '' --skill '' -y

装的是 skills/ 下各 skill 整目录（含 reference/、capmap_lint.py、assets/obsidian/graph.json 等），不是整仓其它文件。

然后对 Agent 说：「按 capmap-init 初始化文档目录」（选定 docs_root）。没有这一步，方案/底图没有落点。

Cursor / Codex 等项目级目录是 .agents/skills/，路径与契约一致。
若只装到 Claude Code 的 .claude/skills/，请保证业务仓仍有一份 .agents/skills/capmap-（或对 .agents 做 junction/symlink），否则读不到 capmap.yaml。

手动拷贝

mkdir -p your-repo/.agents/skills
cp -R skills/capmap- your-repo/.agents/skills/

各 Agent

| Agent | 项目级发现目录 | 做法 |
|-------|----------------|------|
| Cursor | .agents/skills/（亦认 .cursor/skills/） | npx skills add … --agent cursor 或手动拷贝 |
| Codex | .agents/skills/ | --agent codex 或手动拷贝 |
| Claude Code | .claude/skills/ | 先保证 .agents/skills/ 有实体，再链到 .claude/skills/（见下） |
| 其他（Deep Agents、Cline、OpenCode…） | 多数认 .agents/skills/ | --agent  或手动拷贝 |

Claude Code 发现入口（业务仓根已有 .agents/skills/capmap- 时）：

Windows PowerShell
New-Item -ItemType Directory -Force -Path .claude\skills | Out-Null
Get-ChildItem .agents\skills -Directory -Filter "capmap-" | ForEach-Object {
$link = Join-Path ".claude\skills" $_.Name
if (Test-Path $link) { Remove-Item $link -Recurse -Force }
New-Item -ItemType Junction -Path $link -Target $_.FullName | Out-Null
}

macOS / Linux
mkdir -p .claude/skills
for d in .agents/skills/capmap-*; do
ln -sfn "$(pwd)/$d" ".claude/skills/$(basename "$d")"
done

可选 CI：把业务仓 .github/workflows/ 写成调用 uses: ./.agents/skills/capmap-lint（逻辑已在 skill 的 action.yml）。

怎么用

| 你说 | 通常触发 |
|------|----------|
| 「初始化文档目录」 | capmap-init |
| 「写方案 / 需求又变了」 | capmap-scheme |
| 「写规格」 | capmap-spec（体量/大） |
| 「拆切片」 | capmap-slice |
| 「看 frontier / 开 01 / 验收通过」 | capmap-gate |
| 「功能开发完了，更新底图」 | capmap-dev |
| 「写测试点 / 测试通过记一下」 | capmap-test |
| 「写调用约定 / 配置规范」 | capmap-norm |
| 「从 git 反补变更轨迹」 | capmap-backfill |
| 「方案归档」 | capmap-archive |
| 「检查文档体系 / 跑 lint」 | capmap-lint |

不确定阶段时说「按 capmap 来」→ capmap-system。

日常节奏：
- 小：init → scheme（已确认+体量/小）→ 编码 → dev → test → norm → archive
- 大：scheme（体量/大）→ spec → slice（推荐模式后停住）→ 你点名 → gate 循环 → 全验收 → dev → test → …
随时 backfill；改完文档跑 lint。

Obsidian 打开业务仓的 docs_root 即可看图谱（颜色按状态 Tag 区分）。

本地 lint

pip install pyyaml
python .agents/skills/capmap-lint/capmap_lint.py
python .agents/skills/capmap-lint/capmap_lint.py --strict

设计要点

1. 真相源 = 能力底图，不是全局变更台账
2. docs_root 名任意，以 capmap.yaml 为准
3. 方案必须有 ## 变更记录；归档不留 stub
4. 进度 Tag 挂在方案上；切片用类型 切片；能力底图禁止状态 Tag
5. 禁止跳步：验证门 + 大需求规格/拆分门 + 切片全验收才已开发
6. 切片落盘：方案//切片// + 唯一文件名；用户点名才开跑
7. Obsidian：[[唯一文件名]] + Markdown 旁路；init 写入 graph.json 颜色组

本仓库

capmap-skills/
skills/     # 唯一需要安装到业务仓的内容 → .agents/skills/
README.md
LICENSE

- 权威副本 = 本仓库；业务仓只同步 Skill，勿单边改契约
- 改契约请同步更新 skills/capmap-system/reference/decisions.md

License

MIT