code-wiki

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 — 原始数据（不可变）

• 代码源文件本身（src/、lib/、pkg/ 等，不含AI维护的文档）
• LLM 只读取，永不修改此层
• 这是真相来源

第 2 层：Wiki — 知识层（LLM 拥有）

• 位于仓库的 docs/wiki/ 目录
• 包含：模块摘要、概念页面、交叉引用、架构图、比较分析
• LLM 完全拥有此层——创建页面、更新内容、维护引用一致性
• 人阅读它；LLM 编写它

第 3 层：Schema — 约束层（人机共治）

• 仓库根目录的 AGENTS.md（约 100 行），作为入口地图
• docs/wiki/schema.md，定义 Wiki 的结构规范和工作流
• 告诉 LLM 如何构建 Wiki、遵循什么约定、执行什么工作流
• 与 LLM 随时间共同演进此文件

目录结构

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

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 行）

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

• 不要把所有规则塞进此文件
• 只放：项目概览、Wiki 目录位置、关键约束（3-5 条）、操作入口
• 指向 docs/wiki/ 中的深层信息

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 的约定：

• 页面命名规范
• 必需章节（职责、接口、依赖、文件列表）
• 元数据格式（frontmatter 或表格）
• 交叉引用标记方式

模块页最小模板

# 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/。
• 默认 query 先回答；只有当结果具有复用价值时，才沉淀为新的 Wiki 页面。

关键原则

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

参考资源

• references/methodology.md — Karpathy LLM Wiki 和 OpenAI Harness Engineering 方法论摘要，包含设计哲学和背景原理