AI 研发流程重塑指南

从规范、技能到知识沉淀——用 AI 工具重塑研发流程的实践参考

面向全体研发人员 · 整合三套业界一线实践，构成一个完整的 AI 研发闭环

规范先行 · OpenSpec 执行纪律 · Skills 代码导航 · CodeGraph 知识沉淀 · LLM Wiki 更新于 2026-06

一、总览：四者如何构成闭环 ¶

AI 编码助手很强大，但也容易"翻车"：需求没对齐就开干、代码堆成屎山、文档永远过时、团队知识散落在聊天记录里，还有——AI 光是搞懂你的代码库就要烧掉一大笔 token。本指南用四套互补的实践，分别解决这四个层面的问题。

维度	实践来源	解决的核心问题	一句话定位
开发范式	Fission-AI/OpenSpec	需求只活在聊天里 → 结果不可预测	动手前先用规格对齐"建什么"
常用技能	mattpocock/skills	AI 不听话、啰嗦、写出烂代码、堆屎山	一组小而可组合的执行纪律
代码导航	colbymchenry/codegraph	AI 靠 grep/glob/Read 翻代码库 → token 与工具调用黑洞	给 AI 一个预索引的代码知识图谱，降本提速
知识库	Karpathy LLM Wiki	知识一次性、不积累、维护负担重	用 LLM 增量维护一个会复利增长的知识库

闭环示意

          ┌─────────────────────────────────────────────┐
          │              团队 / 项目知识库                │
          │   （LLM Wiki：spec、ADR、领域模型、决策记录）  │
          └─────────────────────────────────────────────┘
             ▲  沉淀（archive / lint / ingest）     │ 读取（query / 复用）
             │                                     │
  ┌──────────┴──────────┐               ┌───────────┴──────────┐
  │   规范先行 OpenSpec   │ ── 喂给 AI ──▶ │   执行纪律 Skills      │
  │ propose→apply→archive │               │ grill / tdd / diagnose │
  └──────────────────────┘               └───────────▲──────────┘
                                                     │ 代码上下文
                                        ┌────────────┴────────────┐
                                        │   代码导航 CodeGraph      │
                                        │  预索引图谱 · 自动同步     │
                                        └─────────────────────────┘

OpenSpec 产出结构化的规格与任务清单，是 AI 编码的"输入"（对齐"建什么"）。
Skills 在编码过程中提供纪律（对齐、TDD、调试、架构），保证"输出"质量。
CodeGraph 给 AI 一个预索引的代码知识图谱，让它低成本读懂"现有代码"，降本提速。
LLM Wiki 把过程中产生的规格、决策、领域知识沉淀下来，供下一个需求复利增长。

💡

四者都是轻量、可裁剪、模型无关的。不要全盘照搬，按团队现状挑着用。

二、开发范式 · OpenSpec（规范先行） ¶

来源：github.com/Fission-AI/OpenSpec · MIT 协议 · "The most loved spec framework"

2.1 是什么

OpenSpec 是面向 AI 编码助手的规格驱动开发（Spec-Driven Development, SDD）框架。核心主张：需求只活在聊天历史里时，AI 的产出是不可预测的。OpenSpec 在"写代码之前"加一层轻量规格，让人和 AI 先就"要建什么"达成一致。

2.2 设计哲学

→ fluid not rigid        （流动而非僵化）
→ iterative not waterfall （迭代而非瀑布）
→ easy not complex        （简单而非复杂）
→ built for brownfield not just greenfield （面向存量项目，不只是绿地新项目）
→ scalable from personal projects to enterprises （从个人项目扩展到企业）

它刻意做轻：没有强制的阶段闸门，任何一个产物（proposal / design / tasks）都可以随时改。

2.3 核心工作流：propose → apply → archive

You: /opsx:propose add-dark-mode
AI:  Created openspec/changes/add-dark-mode/
       ✓ proposal.md — 为什么做、改什么
       ✓ specs/       — 需求与场景
       ✓ design.md    — 技术方案
       ✓ tasks.md     — 实现清单
     Ready for implementation!

You: /opsx:apply
AI:  Implementing tasks...
       ✓ 1.1 Add theme context provider
       ✓ 1.2 Create toggle component
     All tasks complete!

You: /opsx:archive
AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
     Specs updated. Ready for the next feature.

命令	阶段	作用
`/opsx:propose <想法>`	规划	生成一个变更文件夹，包含 proposal / specs / design / tasks
`/opsx:apply`	实现	按 tasks 清单逐步实现
`/opsx:archive`	收尾	归档变更，更新主线 specs，进入下一个特性

2.4 变更产物结构

每个变更（change）拥有独立目录：

openspec/changes/<change-id>/
├── proposal.md   # 动机：为什么做、改了什么
├── specs/        # 需求与验收场景（Given/When/Then 风格）
├── design.md     # 技术方案：怎么实现、权衡
└── tasks.md      # 实现清单：可独立认领的任务

归档后进入 openspec/changes/archive/<日期>-<change-id>/，主线 specs（如 openspec/specs/）随之更新。

2.5 扩展工作流（可选）

通过 openspec config profile 切换到扩展配置，额外获得：/opsx:new、/opsx:continue、/opsx:ff（fast-forward）、/opsx:verify、/opsx:bulk-archive、/opsx:onboard。

2.6 为什么选它（横向对比）

对比对象	评价
vs Spec Kit（GitHub）	Spec Kit 严谨但偏重，阶段闸门僵化、Markdown 多、需 Python 环境。OpenSpec 更轻，可自由迭代。
vs Kiro（AWS）	Kiro 强大但锁定其 IDE、仅限 Claude 模型。OpenSpec 与你现有的工具兼容。
vs 什么都不做	没有 spec 的 AI 编码 = 模糊的提示词 + 不可预测的结果。OpenSpec 在不增加繁文缛节的前提下带来可预测性。

2.7 使用注意

模型选择：OpenSpec 在高推理能力模型上效果最好，规划与实现阶段均推荐使用顶级模型。
上下文卫生：开始实现前清理上下文窗口，全程保持良好的上下文卫生——spec 之所以有效，前提是 AI 有干净的上下文。
工具兼容：通过 slash commands 兼容 20+ AI 助手。

2.8 快速上手

# 需要 Node.js 20.19.0+
npm install -g @fission-ai/openspec@latest

cd your-project
openspec init

# 然后告诉 AI
/opsx:propose <你想要构建的东西>

三、常用技能 · mattpocock/skills（执行纪律） ¶

来源：github.com/mattpocock/skills · "Skills for Real Engineers"

3.1 是什么

Matt Pocock 从自己 .claude 目录里提炼的、每天真实工程中使用的 Agent 技能集合。定位明确："为真正的工程服务，而非 vibe coding（随性编码）"。

它的设计原则与 OpenSpec 一脉相承：小（每个技能职责单一）、易改造、可组合、模型无关，基于数十年的工程经验沉淀。

作者明确不认同 GSD、BMAD、Spec-Kit 这类"接管整个流程"的方案——它们虽然帮你管流程，但也夺走了你的控制权，且流程本身的 bug 很难修。本仓库走的是相反路线。

3.2 它解决的四大失败模式

这是理解整套技能的钥匙：

① AI 没做对我想要的（对齐失败）

"没有人能完全说清自己想要什么。" ——《程序员修炼之道》

最常见的失败模式就是错位：你以为对方懂了，结果做出来完全不对。AI 时代同样存在人与 Agent 之间的沟通鸿沟。

解法 = Grilling（拷问式对齐）：在动手前，让 Agent 就你要做的东西提出一连串详细问题，逐个击穿决策树的每个分支。

/grill-me —— 非代码场景
/grill-with-docs —— 同上，外加领域文档 goodies（见下）

💡

这是最受欢迎的技能。每次想做改动前都用一次。

② AI 太啰嗦（语言不统一）

"有了统一语言，开发者之间的对话与代码的表达都源自同一个领域模型。" —— Eric Evans，《领域驱动设计》

项目初期，开发与领域专家往往说着不同语言。Agent 也是：被丢进项目、靠猜去理解术语，于是 1 个词能说清的事它要用 20 个词。

解法 = 共享语言（Shared Language）：用一份文档帮 Agent 解码项目黑话，从而变得精炼。

改造前："当一个课程某个 section 里的 lesson 被做成 'real'（即在文件系统里给定一个位置）时，会有问题。"
改造后："materialization cascade 有问题。"

这份精炼会每个 session 都持续受益，还有额外红利：命名一致、代码库更易被 Agent 导航、Agent 思考消耗 token 更少。

载体：/grill-with-docs 在拷问的同时帮你建立共享语言，并把难以解释的决策写进 ADR（架构决策记录）。作者称之为"本仓库最酷的单个技巧"。

③ 代码就是跑不通（反馈回路缺失）

"永远迈小而刻意的步子。反馈的速度就是你的速度上限。" ——《程序员修炼之道》

对齐之后，Agent 仍可能写出烂代码——这时要看反馈回路。没有"代码到底跑没跑通"的反馈，Agent 就是盲飞。

解法 = 反馈回路三件套：静态类型、浏览器访问、自动化测试。测试层面，红-绿-重构循环至关重要：先写失败的测试，再让测试通过。/tdd 把这套循环封装进任意项目；/diagnosing-bugs 把最佳调试实践包成一个简单循环。

④ 我们堆出了一个"泥球"（架构腐化）

"每天都要投资于系统的设计。" —— Kent Beck，《解析极限编程》
"最好的模块是深的：用简单的接口暴露大量功能。" —— John Ousterhout，《软件设计哲学》

Agent 能极大加速编码，于是也加速了软件熵增——代码库以前所未有的速度变复杂。

解法 = 重视代码设计：/to-prd 在生成 PRD 前先拷问你会动到哪些模块；/improve-codebase-architecture 帮你拯救已经变成泥球的代码库。建议每隔几天对代码库跑一次。

3.3 技能分类轴：谁能调用它

技能沿一条轴划分——谁可以触发它：

用户调用（user-invoked）：只有你手动输入才会触发（如 /grill-me），职责是编排流程。
模型调用（model-invoked）：你手动触发或 Agent 在任务匹配时自动调用，承载可复用的纪律。

规则：用户调用技能可以调用模型调用技能，但不能调用另一个用户调用技能。

3.4 技能清单

Engineering（日常代码工作）

技能	类型	作用
`ask-matt`	用户	问"我该用哪个技能/流程"，是本仓库用户调用技能的路由器
`grill-with-docs`	用户	拷问式对齐 + 建立项目领域模型、精炼术语、就地更新 `CONTEXT.md` 与 ADR
`triage`	用户	把 issue 在一套 triage 角色状态机中流转
`improve-codebase-architecture`	用户	扫描代码库寻找"加深模块"的机会，生成可视化 HTML 报告，再就选定项做拷问
`setup-matt-pocock-skills`	用户	为本仓库配置工程技能（issue 跟踪器、triage 标签、领域文档布局）。使用其他工程技能前每个仓库跑一次
`to-issues`	用户	用垂直切片把任意计划/规格/PRD 拆成可独立认领的 issue
`to-prd`	用户	把当前对话直接合成成 PRD 并发布到 issue 跟踪器（不再面试，只综合已讨论内容）
`prototype`	用户	建一次性原型来厘清设计——终端 app 或多个差异极大的 UI 变体
`diagnosing-bugs`	模型	硬 bug 与性能回归的纪律化诊断循环：复现→最小化→假设→插桩→修复→回归测试
`tdd`	模型	红绿重构的 TDD，一次一个垂直切片地构建功能或修 bug
`domain-modeling`	模型	主动建立并精炼项目领域模型——挑战术语、边界场景压测、就地更新 `CONTEXT.md` 与 ADR
`codebase-design`	模型	设计深模块的共享纪律与词汇：小接口背后的大量行为、放在干净的接缝处、可通过接口测试

Productivity（通用工作流，与代码无关）

技能	类型	作用
`grill-me`	用户	围绕计划/设计被无情拷问，直到决策树每个分支都被解决
`handoff`	用户	把当前对话压缩成交接文档，让另一个 Agent 接力
`teach`	用户	跨多个 session 教你一项新技能/概念，用当前目录作为有状态的教学工作区
`writing-great-skills`	用户	写好/编辑技能的参考：让技能可预测的词汇与原则
`grilling`	模型	拷问的可复用循环，是 `grill-me` 与 `grill-with-docs` 的底层

Misc（偶尔一用的工具）

技能	作用
`git-guardrails-claude-code`	给 Claude Code 配置 hook，在危险 git 命令（push、reset --hard、clean 等）执行前拦截
`migrate-to-shoehorn`	把测试文件从 `as` 类型断言迁移到 @total-typescript/shoehorn
`scaffold-exercises`	创建练习目录结构（章节/题目/解答/讲解）
`setup-pre-commit`	用 Husky + lint-staged 配 pre-commit（Prettier、类型检查、测试）

3.5 最值得团队立即采用的三个技能

对齐

/grill-with-docs

每次改动前的对齐 + 领域语言沉淀。与 OpenSpec 的 propose 天然互补。

反馈

/tdd

红绿重构，给 AI 稳定的反馈，显著提升产出质量。

反熵

/improve-codebase-architecture

定期"反熵"，防止 AI 加速下的架构腐化。

3.6 安装与上手（30 秒）

# 1. 运行安装器
npx skills@latest add mattpocock/skills

# 2. 勾选你要的技能、要装到哪些编码 Agent 上
#    （务必勾选 /setup-matt-pocock-skills）

# 3. 在 Agent 里运行 /setup-matt-pocock-skills，它会询问：
#    - 用哪个 issue 跟踪器（GitHub / Linear / 本地文件）
#    - triage 时给 ticket 打哪些标签
#    - 文档存到哪

四、代码导航 · CodeGraph（上下文供给） ¶

来源：github.com/colbymchenry/codegraph · MIT 协议 · "Pre-indexed code knowledge graph, auto syncs on code changes"

🔖

1.0 已发布。官方口号：~16% 更便宜 · ~58% 更少工具调用 · 100% 本地。

4.1 是什么

CodeGraph 是一个预索引的代码知识图谱（knowledge graph）：用 tree-sitter 把整个代码库解析成"符号 + 关系"——函数/类/方法为节点，调用、导入、继承等为边——存进本地 SQLite，再通过 MCP 暴露给 AI Agent。Agent 不再靠 grep/glob/Read 一点点翻文件，而是直接查询图谱：一次调用就能拿到"这个函数被谁调用""改这个符号会影响哪些代码"。

定位一句话：让 AI 低成本地理解你的代码库。它正面回答的是前三套实践都没解决的一个问题——AI 探索代码库本身的成本。

4.2 它解决的问题：探索代码库的 token 黑洞

当 Claude Code 想搞懂一个代码库时，它会派出 Explore 子 Agent，用 grep、glob、Read 一通扫描——每次工具调用都在烧 token。代码库越大，这种"发现式"探索越贵，而答案还常常埋在某个几千行的大文件里。

CodeGraph 的做法：把"探索"从运行时的 grep/glob，变成一次预编译、持续保鲜的索引。Agent 直接查询图谱即可，几乎零文件读取。

基准（Claude Opus 4.8，7 个真实开源库，每臂 4 次取中位数）：平均省 16% 成本、47% token、22% 时间、58% 工具调用。在 VS Code（约 10k 文件）这种大库上甚至做到 64% 更少 token、81% 更少工具调用。

4.3 核心机制

┌─────────────────────────────────────────────────────────────┐
│                      Claude Code / Cursor …                  │
│   "一个请求是如何到达数据库的？"                              │
│         直接调用 CodeGraph 工具，不派 Explore 子 Agent        │
└────────────────────────────┬────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                   CodeGraph MCP Server                       │
│         explore · search · callers · node                    │
└────────────────────────────┬────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────┐
│             本地 SQLite 知识图谱（.codegraph/）               │
│       符号 · 调用边 · 文件 · FTS5 全文搜索                    │
└─────────────────────────────────────────────────────────────┘

四步：抽取（tree-sitter 解析出 AST，提取节点与边）→ 存储（本地 SQLite + FTS5 全文搜索）→ 解析（调用→定义、导入→文件、继承、框架路由）→ 自动同步（原生文件监听 + 防抖增量更新，编码即更新）。

4.4 关键特性

特性	说明
智能上下文构建	一次工具调用返回入口、相关符号与代码片段，无需昂贵的探索 Agent
全文搜索	FTS5 驱动，按名字在整库中瞬间定位代码
影响分析（Impact）	改一个符号前，先查它的调用方/被调用方/完整影响半径
永远新鲜	原生 OS 文件事件（FSEvents/inotify/ReadDirectoryChangesW）+ 防抖自动同步，零配置
框架感知路由	识别 17 个 Web 框架的路由文件，把 URL 模式连到对应 handler
跨语言桥接	Swift↔ObjC、React Native 桥/TurboModules/Fabric、Expo Modules——静态解析跨不过去的语言边界，它补上
20+ 语言	TS/JS、Python、Go、Rust、Java、C#、PHP、Ruby、C/C++、Swift、Kotlin、Scala、Dart、Lua/Luau、R、Svelte、Vue、Astro…
100% 本地	数据不出机器、无需 API key、无外部服务，仅一个 SQLite 文件

4.5 给 Agent 的四个工具

CodeGraph 把工具收到精简的 4 个（实测更短的工具列表能引导 Agent 选对工具、每个 session 省上下文）：

工具	用途
`codegraph_explore`	主力。几乎任何问题一次答完——"X 是怎么工作的"、一个流程、或勘察某片区域
`codegraph_node`	单个符号的完整源码 + 调用链；也可像 Read 工具一样读整个文件
`codegraph_search`	按名字定位符号
`codegraph_callers`	一个函数的所有调用点（含注册为回调的地方）

没有 .codegraph/ 索引的工作区里，MCP server 会自动宣告"未激活"且不暴露任何工具——Agent 照常用自带工具，建不建索引完全由你决定。

4.6 安装与上手（约 3 步）

# 1. 装 CLI 并连接 Agent（自带运行时，无需 Node；也可 npm i -g @colbymchenry/codegraph）
npx @colbymchenry/codegraph            # 交互式：选要接哪些 Agent，自动写 MCP 配置

# 2. 重启 Agent，让 MCP server 生效

# 3. 在每个项目里建索引（建完即自动同步，无需再手动跑）
cd your-project
codegraph init

它会自动配置 Claude Code、Cursor、Codex CLI、opencode、Hermes、Gemini CLI、Antigravity、Kiro——把 CodeGraph 的 MCP server 接进每一个。安装是零配置的：没有配置文件要写、不用按语言单独接线、自动跳过 node_modules/dist/.gitignore 等。

4.7 使用注意

直接查，别再 grep 复核：CodeGraph 就是预建好的索引，再 grep/read 等于重复劳动；把返回的源码当作"已读"。改完文件后留意"过时横幅"（staleness banner）。
索引是你的决定：没建索引时它安静待机，不影响 Agent 正常工作。
大库收益最大：代码库越大，省的 token/工具调用越多（VS Code 级别收益最显著）。
CI 里也能用：codegraph affected 按依赖追踪"改了哪些源文件→该跑哪些测试"，可接进 pre-commit/CI。

4.8 与本指南其他实践的关系

与 OpenSpec：OpenSpec 给"建什么"，CodeGraph 让 AI 低成本读懂"已有什么"——一个对齐新需求，一个理解现有代码，方向互补。
与 Skills：Skills 管执行纪律（对齐/TDD/调试/架构），CodeGraph 管执行时的代码上下文供给——前者提质量，后者降成本，常在同一编码 session 内叠加。
与 LLM Wiki：Wiki 沉淀的是团队决策与领域知识（人向 LLM 喂的资料），CodeGraph 沉淀的是代码结构本身（机器自动从代码抽取）——一个关于"为什么"，一个关于"代码长什么样"。

五、知识库 · Karpathy LLM Wiki（知识沉淀） ¶

来源：Andrej Karpathy 的 Gist《LLM Wiki》

📖

这是一份"理念文件"，设计成直接复制给你的 LLM Agent（Claude Code、Codex、OpenCode 等），由 Agent 与你协作落地具体实现。

5.1 核心思想：Wiki 是会复利增长的持久产物

大多数人对"LLM + 文档"的体验是 RAG：上传一批文件，查询时 LLM 检索相关片段再生成答案。能用，但 LLM 每次都从零重新发现知识，没有积累。问一个需要综合五份文档的微妙问题，它每次都要重新找、重新拼——什么都没有沉淀下来。NotebookLM、ChatGPT 文件上传、多数 RAG 系统都是这个路子。

LLM Wiki 的思路不同：与其查询时从原始文档检索，不如让 LLM 增量构建并维护一个持久的 wiki——一组结构化、相互链接的 markdown 文件，位于你与原始资料之间。当你加入一份新资料时，LLM 不只是为日后检索做索引，而是阅读它、抽取关键信息、整合进现有 wiki——更新实体页、修订主题摘要、标注新旧数据矛盾、强化或挑战正在演进的综述。知识编译一次后持续保持最新，而非每次查询都重新推导。

关键区别：wiki 是一个持久的、复利增长的产物。 交叉引用已经在那儿了，矛盾已经标出来了，综述已经反映了你读过的所有东西。每加一份资料、每问一个问题，wiki 都变得更丰富。

分工：你（几乎）从不亲自写 wiki——LLM 写并维护全部内容。你负责采集资料、探索方向、提出好问题；LLM 负责所有脏活——总结、交叉引用、归档、记账。

Obsidian 是 IDE，LLM 是程序员，wiki 是代码库。

5.2 适用场景

个人：追踪目标、健康、心理、自我提升；
研究：数周/数月深入一个主题，论文+文章+报告，逐步建成带演进论点的综述 wiki；
读书：每章随读随存，建出角色/主题/情节页及关联；
团队/业务：由 LLM 维护的内部 wiki，喂入 Slack 线程、会议纪要、项目文档、客户通话，人类在环审阅更新；
竞品分析、尽调、行程规划、课程笔记、爱好深挖——任何需要长期积累、希望有条理的场景。

5.3 三层架构

层	说明	谁拥有
Raw sources 原始资料	你精选的资料集合：文章、论文、图片、数据文件。不可变——LLM 只读不改。这是真相之源。	你
The wiki 知识库	LLM 生成的 markdown 目录：摘要、实体页、概念页、对比、总览、综述。LLM 完全拥有此层——创建页、更新、维护交叉引用、保持一致。	LLM
The schema 约定文档	一份文档（Claude Code 用 `CLAUDE.md`、Codex 用 `AGENTS.md`），告诉 LLM wiki 的结构、约定、ingest/query/维护时该遵循的工作流。这是让 LLM 成为纪律化维护者而非普通聊天机器人的关键配置。	共同

5.4 三大操作

Ingest（摄取）

你把新资料丢进 raw 集合并让 LLM 处理。典型流程：LLM 读资料 → 与你讨论要点 → 在 wiki 写一份摘要页 → 更新 index → 跨 wiki 更新相关实体/概念页 → 在 log 追加一条记录。一份资料可能触及 10–15 个 wiki 页。把你摸索出的工作流写进 schema，供后续 session 复用。

Query（查询）

你向 wiki 提问。LLM 检索相关页、阅读、综合出带引用的答案。答案形式多样：markdown 页、对比表、幻灯片（Marp）、图表（matplotlib）、画布。关键洞察：好答案可以回填进 wiki 成为新页。 这样你的探索就和摄取的资料一样，在知识库里复利增长。

Lint（体检）

定期让 LLM 给 wiki 做健康检查，查找：页面间矛盾、被新资料取代的过时断言、没有入链的孤儿页、被提及但缺独立页的重要概念、缺失的交叉引用、可通过一次网搜补上的数据缺口。这让 wiki 在增长中保持健康。

5.5 索引与日志（两个特殊文件）

文件	定位	说明
`index.md`	面向内容	wiki 的目录：每页一个链接 + 一行摘要 + 可选元数据，按类别组织。每次 ingest 都更新。查询时 LLM 先读 index 定位相关页。中等规模（约 100 份资料、数百页）下效果出奇地好，免去了 embedding RAG 的基建。
`log.md`	面向时间	追加式的"发生了什么、何时"记录：ingest、query、lint。每条以一致前缀开头（如 `## [2026-04-02] ingest \| 文章标题`），就能用简单 unix 工具解析：`grep "^## \[" log.md \| tail -5`。

5.6 可选 CLI 工具

wiki 长大后，你可能想建小工具帮 LLM 更高效地操作它。最显而易见的是搜索引擎：小规模下 index 文件够用，长大后需要正经搜索。推荐 qmd：本地 markdown 搜索，混合 BM25/向量检索 + LLM 重排，全在设备本地；既有 CLI（LLM 可 shell 调用）又有 MCP server（LLM 可当原生工具用）。

5.7 实用技巧

Obsidian Web Clipper：浏览器扩展，把网页文章转成 markdown，快速把资料收入 raw 集合。
图片下载到本地：把附件目录固定到 raw/assets/，给"Download attachments"绑快捷键，让 LLM 能直接引用本地图片。
Obsidian graph view：观察 wiki 形态的最佳方式——谁连着谁、哪些是枢纽页、哪些是孤儿。
Marp：基于 markdown 的幻灯片格式，可从 wiki 内容直接生成演示。
Dataview：基于页 frontmatter 跑查询，生成动态表与列表。
wiki 本身就是个 markdown git 仓库：版本历史、分支、协作免费。

5.8 为什么有效

维护知识库的枯燥部分不是阅读或思考，而是记账——更新交叉引用、保持摘要最新、标注矛盾、跨数十页保持一致。人类放弃 wiki，是因为维护负担增长比价值增长更快。LLM 不会厌倦、不会忘了更新交叉引用、一次能碰 15 个文件——wiki 之所以能保持维护，是因为维护成本接近于零。

精神上接近 Vannevar Bush 1945 年的 Memex：一个私人的、主动策展的知识库，文档间有关联轨迹。他当年没解决的正是"谁来做维护"——LLM 解决了这一点。

六、落地路线图与行动清单 ¶

建议按"先轻后重、先个人后团队"的节奏推进，每阶段都验证有效再扩展。

阶段一（第 1–2 周）：单点验证

✅ 个人试用 Skills：npx skills@latest add mattpocock/skills，先启用 /grill-with-docs、/tdd、/diagnosing-bugs。
✅ 挑一个真实小需求：用 /grill-with-docs 对齐 → 用 /tdd 实现，体验"先拷问再动手 + 红绿重构"。
✅ 个人试建 Wiki：把近期读过的 3–5 篇技术资料丢进 raw，让 LLM 建 wiki，感受"复利"。

阶段二（第 3–4 周）：范式落地

✅ 试点 OpenSpec：选 1–2 个项目 openspec init，用 /opsx:propose → apply → archive 走完一个完整变更。
✅ 接入 CodeGraph：在中大型仓库 codegraph init，观察 AI 探索代码时的 token 与工具调用下降（大库收益最显著）。
✅ 约定 CONTEXT.md / ADR 模板：把"共享语言"沉淀进项目，降低 AI 啰嗦与命名漂移。
✅ 配置 git guardrails：用 git-guardrails-claude-code 给危险 git 命令加防护。

阶段三（第 5 周起）：团队级沉淀

✅ 建立团队/项目知识库：用 LLM Wiki 模式聚合 spec、ADR、领域模型、决策记录、会议纪要。
✅ 定期架构体检：每 3–5 天对核心仓库跑 /improve-codebase-architecture，反熵。
✅ 固化 schema：把团队认可的 wiki 约定、ingest/query/lint 工作流写进 CLAUDE.md / AGENTS.md。
✅ 衡量：观察需求返工率、AI 产出 bug 率、知识检索效率的变化，据数据迭代。

关键纪律（贯穿全程）

动手前对齐：/grill-with-docs 或 OpenSpec propose，二选一或组合。
保持反馈回路：静态类型 + 自动化测试（TDD）+ 可运行验证。
上下文卫生：开始实现前清理上下文窗口，spec/skill 才能真正生效。
知识不进聊天历史：决策、综述、对比都回填到 wiki，让探索复利增长。
定期反熵：代码架构与知识库都要周期性体检。
给 AI 便宜的代码上下文：大库用 CodeGraph 预索引，别让 Agent 靠 grep 翻代码烧 token。

七、研发全链路速查图 ¶

从需求到归档——每一步该用哪个工具/技能的速查图。颜色编码:OpenSpec(规范) · Skills(技能) · CodeGraph(导航) · LLM Wiki(知识)。

7.1 全链路速查图

OpenSpec 规范 Skills 技能 CodeGraph 导航 LLM Wiki 知识

需求对齐

对齐"建什么"

/grill-with-docs /grill-me /opsx:propose Wiki · 查 ADR

设计 / 架构

定方案、防烂设计

/prototype codebase-design codegraph_explore design.md Wiki · 查方案

任务拆解

拆可独立认领的活

/to-issues /to-prd tasks.md

实现编码

高质量落地

/tdd /opsx:apply codegraph_explore domain-modeling

调试排障

快速定位根因

/diagnosing-bugs codegraph_callers · impact Wiki · 查同类

测试质检

防回归

/tdd setup-pre-commit codegraph affected

评审 / 重构

反熵、防泥球

/improve-codebase-architecture codebase-design /simplify

提交 / 发布

安全上线

git-guardrails codegraph affected · CI

沉淀归档

复利积累

/opsx:archive handoff · teach Wiki · ingest/lint

贯穿全程（横切关注点）

CodeGraph · 代码上下文 LLM Wiki · 知识查询 git-guardrails · 危险命令防护上下文卫生 · 实现前清窗口

7.2 阶段 × 工具技能映射表

阶段	目标	OpenSpec	Skills	CodeGraph	LLM Wiki
① 需求对齐	对齐"建什么"	`/opsx:propose`(proposal/specs)	`/grill-me`、`/grill-with-docs`	—	query:查相关 ADR/决策
② 设计 / 架构	定方案、防烂设计	`propose` 的 design.md	`/prototype`、`codebase-design`	`codegraph_explore` 摸清现有结构	query:查领域模型/历史方案
③ 任务拆解	拆可独立认领的活	`propose` 的 tasks.md	`/to-issues`、`/to-prd`	—	—
④ 实现编码	高质量落地	`/opsx:apply`(按 tasks)	`/tdd`、`domain-modeling`	`codegraph_explore`/`node` 读懂代码	—
⑤ 调试排障	快速定位根因	—	`/diagnosing-bugs`	`codegraph_callers`/`impact` 算影响半径	query:查类似问题记录
⑥ 测试质检	防回归	—	`/tdd`、`setup-pre-commit`	`codegraph affected` 只跑受影响测试	—
⑦ 评审 / 重构	反熵、防泥球	—	`/improve-codebase-architecture`、`codebase-design`、`/simplify`	`codegraph_explore` 评估影响	—
⑧ 提交 / 发布	安全上线	—	`git-guardrails-claude-code`	`codegraph affected` 接进 CI	—
⑨ 沉淀归档	复利积累	`/opsx:archive`(更新主线 spec)	`handoff`、`teach`	—	ingest/lint(回填 ADR/综述)、更新 index/log

7.3 贯穿全程的横切关注点

CodeGraph · 代码上下文:任何时候让 AI 理解/查代码,优先 codegraph_explore,别让它 grep 翻库。
LLM Wiki · 知识查询:动手前后查一眼 ADR、领域模型、历史决策,避免重复踩坑。
git-guardrails · 安全防护:危险 git 命令(push、reset --hard、clean)执行前拦截。
上下文卫生:进入实现前清理上下文窗口——spec/skill/codegraph 要生效,前提是 AI 有干净上下文。

7.4 不知道用哪个?一句话决策

完全没头绪 → /ask-matt(本仓库技能的路由器,问它"我该用哪个")。
按场景直选:对齐需求 → /grill-with-docs;厘清设计 → /prototype;写代码/修 bug → /tdd;排查疑难 → /diagnosing-bugs;代码变烂 → /improve-codebase-architecture;读懂大库 → codegraph_explore;沉淀决策 → Wiki ingest。

💡

经验法则:对齐优先于动手(grill/propose)、反馈优先于堆代码(tdd/diagnose)、降本优先于蛮力(codegraph)、沉淀优先于聊天(wiki)。四者叠加,就是 AI 时代的研发纪律。

附录 A：术语表 ¶

术语	含义
SDD	规格驱动开发：写代码前先用规格对齐需求。OpenSpec 的核心理念。
ADR	架构决策记录：用简短文档记录一个架构决策的背景、决策与后果。
Grilling	拷问式对齐：让 AI 围绕计划/设计反复提问，逐个击穿决策树分支。
Shared Language	共享语言/统一语言：团队与 AI 共用的领域术语，降低啰嗦与命名漂移。
Deep Module	深模块：小接口背后的大量行为，良好模块设计的标志（Ousterhout）。
Red-Green-Refactor	红-绿-重构：先写失败测试（红）、让其通过（绿）、再重构。TDD 的核心循环。
Vertical Slice	垂直切片：端到端贯穿各层的一个可交付功能单元。
Brownfield	存量项目（相对于全新"绿地"项目）。
RAG	检索增强生成：查询时从原始文档检索片段再生成。LLM Wiki 的对立参照。
user / model-invoked	用户调用/模型调用技能：前者只能手动触发负责编排，后者可被 Agent 自动调用承载纪律。
代码知识图谱	把代码库解析成"符号 + 关系"的图结构（函数/类/方法为节点，调用/导入/继承为边），CodeGraph 的核心产物。
MCP	模型上下文协议：让 AI Agent 以标准化方式调用外部工具/数据源的协议。CodeGraph 通过它把图谱暴露给 Agent。
Impact Analysis	影响分析：改一个符号前，查它的调用方/被调用方/完整影响半径，评估"会波及哪些代码"。
codegraph_explore	CodeGraph 的主力工具：一次调用回答"X 怎么工作"、一个流程、或勘察某片区域，返回相关符号源码。
tree-sitter	增量式语法解析库，CodeGraph 用它把源码解析成 AST 以抽取符号与关系。

附录 B：参考链接 ¶

OpenSpec（开发范式）：github.com/Fission-AI/OpenSpec
mattpocock/skills（常用技能）：github.com/mattpocock/skills
colbymchenry/codegraph（代码导航）：github.com/colbymchenry/codegraph
Karpathy LLM Wiki（知识库）：gist.github.com/karpathy/...
qmd（wiki 本地搜索引擎）：github.com/tobi/qmd
Obsidian：obsidian.md