参照karpathy和openai分享的知识库组织方法论,以代码为raw source层创建文档地图的skill指导。
此 skill 指导 IDE/Agent 为代码仓库构建和维护一个持久的、结构化的知识库(Wiki)。核心理念:代码是原始数据,Wiki 是 LLM 维护的中间层,Schema 是纪律约束。Wiki 是可复利的产物——每次 ingest 和 query 都让它更丰富,而非从零重新发现。
代码仓库的知识库由三层构成:
src/、lib/、pkg/ 等,不含AI维护的文档)docs/wiki/ 目录AGENTS.md(约 100 行),作为入口地图docs/wiki/schema.md,定义 Wiki 的结构规范和工作流默认采用最小可行结构;先把骨架跑通,不要一开始照搬很重的文档体系。
repo/
├── AGENTS.md
├── docs/
│ └── wiki/
│ ├── index.md
│ ├── log.md
│ ├── schema.md
│ ├── modules/
│ ├── concepts/
│ └── crossref/
如果仓库后续需要更完整的 design-docs/、exec-plans/、references/,再逐步补充;不要为了“像样”先生成一大堆空文档。
当需要将代码模块/文件导入知识库时执行:
docs/wiki/modules/ 下创建模块页面,包含:index.md 中追加条目(链接 + 摘要 + 元数据)log.md 中记录本次操作批量摄取:当用户要求处理整个仓库或大范围模块时,按依赖拓扑排序,逐模块执行上述流程。
当用户针对代码仓库提问时执行:
index.md 定位相关页面关键:高质量的查询结果(比较分析、架构洞察、发现的连接)应沉淀为新页面归档回 Wiki。探索也能复利增长。
定期或在用户要求时执行 Wiki 健康检查:
| 检查项 | 说明 | 修复动作 |
|---|---|---|
| 矛盾 | 页面间的矛盾描述 | 标记矛盾,回溯源代码确认,更新为正确版本 |
| 过时 | 被代码变更取代的旧描述 | 对比源代码,更新 Wiki 内容 |
| 孤立页面 | 没有入站链接的页面 | 在相关页面添加引用链接 |
| 缺失页面 | 被提及但未创建的重要概念 | 创建占位页面并标记待补充 |
| 缺失引用 | 应链接但未链接的页面 | 补充交叉引用 |
| 数据空白 | 可从代码中提取但未记录的信息 | 补充到对应页面 |
精简的入口文件,遵循"地图而非百科"原则:
docs/wiki/ 中的深层信息# Wiki 索引
## 模块
| 页面 | 摘要 | 关键文件 | 更新日期 |
|------|------|----------|----------|
| [auth](modules/auth.md) | 用户认证与授权 | src/auth/*.go | 2026-04-09 |
## 概念
| 页面 | 摘要 | 涉及模块 | 更新日期 |
|------|------|----------|----------|
| [error-handling](concepts/error-handling.md) | 统一错误处理模式 | auth, payment | 2026-04-09 |
## 交叉引用
| 页面 | 摘要 | 更新日期 |
|------|------|----------|
| [module-dependencies](crossref/module-dependencies.md) | 模块间依赖关系图 | 2026-04-09 |
## [2026-04-09] ingest | auth 模块
- 创建 modules/auth.md
- 更新 index.md
- 发现与 payment 模块的交叉引用,更新 crossref/module-dependencies.md
## [2026-04-09] query | 认证流程如何工作?
- 综合 auth.md 和 error-handling.md 回答
- 沉淀:创建 concepts/auth-flow.md
## [2026-04-09] lint | 周度检查
- 修复:payment.md 中过时的 API 描述
- 补充:data-flow.md 缺失的消息队列章节
定义此 Wiki 的约定:
# auth
## 职责
## 关键接口 / 类型
## 依赖关系
## 关键文件
## 备注 / 待确认
用户请求
├── "生成代码地图" / "文档化仓库"
│ → 检查 docs/wiki/ 是否存在
│ ├── 不存在 → 初始化 Wiki 结构(创建目录、schema.md、index.md、log.md)
│ └── 已存在 → 询问处理范围(全量 / 指定模块)
│ → 执行 Ingest 操作
│
├── 针对代码提问
│ → 执行 Query 操作
│ → 判断答案是否有归档价值
│
├── "检查文档" / "lint wiki"
│ → 执行 Lint 操作
│
├── "更新代码地图"
│ → 识别变更的代码文件
│ → 对变更部分执行 Ingest(增量更新)
│
└── "初始化 AGENTS.md"
→ 基于已有 Wiki 内容,生成精简的入口地图
AGENTS.md、index.md、log.md、schema.md 四个骨架文件,再逐步补内容。modules/,只有在跨模块复用明显时再补 concepts/ 和 crossref/。references/methodology.md — Karpathy LLM Wiki 和 OpenAI Harness Engineering 方法论摘要,包含设计哲学和背景原理