code-wiki

参照karpathy和openai分享的知识库组织方法论,以代码为raw source层创建文档地图的skill指导。

1475505
開発者 1475505
その他 · 更新日: 7 months ago
0
スター
0
Forks
コミュニティ
BBB
安全性:
普通
BBB
品質:

name: code-wiki description: 此 skill 适用于为代码仓库生成和维护结构化知识库(代码地图)。当用户要求"生成代码地图"、"建立代码 wiki"、"文档化代码仓库"、"创建 CLAUDE.md/AGENTS.md"、"代码知识库管理"、"ingest 代码"、"lint 文档"时触发。基于 Karpathy LLM Wiki 模式和 OpenAI Harness Engineering 方法论,将代码仓库转化为 LLM 可持续维护的结构化知识体系。

Code Wiki — 代码仓库知识库管理

概述

此 skill 指导 IDE/Agent 为代码仓库构建和维护一个持久的、结构化的知识库(Wiki)。核心理念:代码是原始数据,Wiki 是 LLM 维护的中间层,Schema 是纪律约束。Wiki 是可复利的产物——每次 ingest 和 query 都让它更丰富,而非从零重新发现。

三层组织结构

代码仓库的知识库由三层构成:

第 1 层:Raw — 原始数据(不可变)

第 2 层:Wiki — 知识层(LLM 拥有)

第 3 层:Schema — 约束层(人机共治)

目录结构

默认采用最小可行结构;先把骨架跑通,不要一开始照搬很重的文档体系。

repo/
├── AGENTS.md
├── docs/
│   └── wiki/
│       ├── index.md
│       ├── log.md
│       ├── schema.md
│       ├── modules/
│       ├── concepts/
│       └── crossref/

如果仓库后续需要更完整的 design-docs/、exec-plans/、references/,再逐步补充;不要为了“像样”先生成一大堆空文档。

三种核心操作

操作 1:Ingest(摄取)

当需要将代码模块/文件导入知识库时执行:

  1. 扫描:读取目标代码文件,理解其结构、依赖、职责
  2. 讨论:与用户确认关键要点、设计意图、边界条件
  3. 写摘要页:在 docs/wiki/modules/ 下创建模块页面,包含:
    • 一句话职责描述
    • 核心类型/接口清单
    • 对外依赖和被依赖关系
    • 关键文件列表(带路径)
  4. 更新索引:在 index.md 中追加条目(链接 + 摘要 + 元数据)
  5. 更新关联页面:刷新相关概念页面、交叉引用页面
  6. 追加日志:在 log.md 中记录本次操作

批量摄取:当用户要求处理整个仓库或大范围模块时,按依赖拓扑排序,逐模块执行上述流程。

操作 2:Query(查询)

当用户针对代码仓库提问时执行:

  1. 读索引:先读 index.md 定位相关页面
  2. 深入阅读:读取相关 Wiki 页面,必要时回溯源代码验证
  3. 综合回答:生成带引用的答案,标注信息来源页面

关键:高质量的查询结果(比较分析、架构洞察、发现的连接)应沉淀为新页面归档回 Wiki。探索也能复利增长。

操作 3:Lint(检查)

定期或在用户要求时执行 Wiki 健康检查:

检查项 说明 修复动作
矛盾 页面间的矛盾描述 标记矛盾,回溯源代码确认,更新为正确版本
过时 被代码变更取代的旧描述 对比源代码,更新 Wiki 内容
孤立页面 没有入站链接的页面 在相关页面添加引用链接
缺失页面 被提及但未创建的重要概念 创建占位页面并标记待补充
缺失引用 应链接但未链接的页面 补充交叉引用
数据空白 可从代码中提取但未记录的信息 补充到对应页面

核心文档格式

AGENTS.md(入口地图,约 100 行)

精简的入口文件,遵循"地图而非百科"原则:

index.md(内容索引)

# 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 |

log.md(时间线,仅追加)

## [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 缺失的消息队列章节

schema.md(结构规范)

定义此 Wiki 的约定:

模块页最小模板

# auth

## 职责
## 关键接口 / 类型
## 依赖关系
## 关键文件
## 备注 / 待确认

工作流决策树

用户请求
├── "生成代码地图" / "文档化仓库"
│   → 检查 docs/wiki/ 是否存在
│   ├── 不存在 → 初始化 Wiki 结构(创建目录、schema.md、index.md、log.md)
│   └── 已存在 → 询问处理范围(全量 / 指定模块)
│   → 执行 Ingest 操作
│
├── 针对代码提问
│   → 执行 Query 操作
│   → 判断答案是否有归档价值
│
├── "检查文档" / "lint wiki"
│   → 执行 Lint 操作
│
├── "更新代码地图"
│   → 识别变更的代码文件
│   → 对变更部分执行 Ingest(增量更新)
│
└── "初始化 AGENTS.md"
    → 基于已有 Wiki 内容,生成精简的入口地图

默认执行策略

关键原则

  1. 地图而非百科:AGENTS.md 是地图(~100行),不是手册。深层信息放在 Wiki 页面中。
  2. 渐进式披露:从小的稳定切入点开始,按需深入。不要一次性把所有信息塞进上下文。
  3. Wiki 可复利:好的查询结果沉淀回 Wiki。知识只增不减。
  4. 源代码是真相:Wiki 描述与代码矛盾时,以代码为准。Lint 的核心就是消除这种漂移。
  5. 结构先于内容:先建立 index.md 和 schema.md 的骨架,再逐步填充内容。
  6. 人筛选、机记账:人决定什么重要,LLM 负责所有繁琐的交叉引用和一致性维护。

参考资源

🔓 サインインしてさらに解放
GitHub でサインイン