# coding wiki skill

**Repository Path**: cpsoft13/coding-wiki-skill

## Basic Information

- **Project Name**: coding wiki skill
- **Description**: 参考卡帕西的llm wiki方案为vibe coding构建的skill
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-28
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Coding Wiki Skill

> 跟 AI 说话就行。它会记住每个 bug、每次决策、每条教训，不再反复踩坑。

---

## 为什么需要它

用 AI 写代码，你一定遇到过这些问题：

- 🔄 **反复踩坑** — 修复过的 bug，换个会话 AI 又犯同样的错
- 🚀 **长任务跑偏** — 让 AI 重构一个模块，三小时后 scope 完全失控
- 🧪 **改完不知道测什么** — AI 说"已测试"，但只跑了几个单元测试
- 📂 **知识全靠对话** — 架构决策、bug 根因全在聊天记录里，换个会话什么都没了

Coding Wiki Skill 把 **Karpathy LLM Wiki** 和 **Coding Agent Harness** 落地为一套对话驱动的工作流。你只需要跟 AI 说话，它自动处理一切。

---

## 理论基础

### 🧠 Karpathy LLM Wiki — 让 AI 有了长期记忆

Andrej Karpathy 提出的 [LLM Wiki](https://gist.github.com/karpathy) 方法论，核心理念：

> **知识一次编译，持续保鲜，越用越厚。** 人类负责提问与策展，AI 承担全部维护工作。

三层架构：

```
Raw 层（你说的 / 你写的）
  需求文档、bug 报告、会议纪要、架构决策
       ↓ AI 自动编译
Wiki 层（AI 生成的结构化知识）
  含 [[wikilink]] 双向链接的需求/bug/决策/教训页面
       ↓
Graph 层（知识图谱）
  可视化所有页面间的关联网络
```

**为什么有效**：AI 修改代码前，先在 Wiki 层检索——上次修过什么、为什么这么改、踩了什么坑。不会每个新会话从零开始。

### ⚙️ Coding Agent Harness — 让 AI 长程任务不跑偏

[Coding Agent Harness](https://github.com/FairladyZ625/coding-agent-harness) 来自 [Agora](https://github.com/FairladyZ625/Agora) 项目的真实开发实践——一个人配合 AI，三周半产生了 15 万行源码、1284 次提交、413 篇 walkthrough、441 个任务计划。

核心模块：

| 模块 | 解决什么 |
|------|---------|
| Planning Loop | AI 在长任务中不偏离目标 |
| Long-Running Task Protocol | 多轮任务可审查、可停止 |
| SSoT 治理 | 单一事实源，避免真相分裂 |
| Regression 体系 | 改了 A 不破坏 B |
| Walkthrough 收口 | 每轮迭代有据可查 |
| Worktree 并行 | 多 Agent 并行不冲突 |

核心信条：文档写给 Agent 看 / 上下文越准越好 / 强制流程优于口头约定 / 长程任务先设计合同再开放执行。

### 🤝 两者的结合

LLM Wiki 管**知识**（记住过去），Harness 管**行为**（不跑偏）。Coding Wiki Skill 把两者统一在 `raw → wiki` 管道下，你只需要跟 AI 说话。

---

## 快速开始

### 1. 安装 Skill

```
你：「帮我安装 coding-wiki skill」
AI：[自动克隆仓库到 skills 目录]
```



### 2. 初始化项目

```
你：「帮我初始化项目 wiki」
AI：请问项目叫什么？技术栈是什么？
你：「流媒体平台，Go + WebRTC」
AI：[自动执行初始化，生成完整目录结构]
```

初始化后项目结构：

```
your-project/
├── AGENTS.md              ← AI 每次会话必读的行为规则
├── CLAUDE.md              ← Claude Code 兼容版
├── raw/                   ← 原始资料（你写的或口述的）
│   ├── bugs/
│   ├── requirements/
│   ├── decisions/
│   ├── meetings/
│   ├── planning/
│   ├── test-qa/
│   └── walkthroughs/
├── wiki/                  ← 结构化知识（AI 生成维护）
│   ├── bugs/              ← Bug 记录（含根因分析）
│   ├── requirements/      ← 结构化需求
│   ├── decisions/         ← 架构决策记录（ADR）
│   ├── lessons/           ← ⭐ 经验教训（防止重复犯错的关键）
│   ├── syntheses/         ← 主题总结
│   ├── planning/          ← 任务规划 + Feature SSoT
│   ├── test-qa/           ← 回归体系
│   ├── walkthroughs/      ← 交接文档
│   └── reference/         ← 标准参考文件
└── graph/                 ← 知识图谱
    └── graph.html
```

### 3. 三种规模

| 级别 | 包含内容 | 适合 |
|------|---------|------|
| **lite** | 基础目录 + AGENTS.md + Planning + SSoT | 小项目、试水 |
| **standard** | lite + Cadence Ledger + Walkthrough + 全部 Reference | **大多数项目** |
| **full** | standard + 完整子目录 + 全部模板 | 大型团队项目 |

```
你：「用 lite 模式初始化」
AI：[只生成最精简的结构]
```

---

## 日常使用 — 你只需要说话

### 🐛 遇到 Bug

```
你：「RTSP 拉流 30 分钟后内存从 200MB 涨到 2GB，帮我记录一下」

AI：
  📝 已创建 bug 报告：raw/bugs/rtsp-memory-leak.md
  ✅ 已生成 wiki 页面：wiki/bugs/bug-20260428-rtsp-memory-leak.md
  🔗 关联到 [[lesson-buffer-cleanup]]
```

修完之后：

```
你：「修好了，帮我记录修复过程」

AI：
  📋 Bug 修复记录已更新：
     根因：GStreamer source 未正确 unref → buffer 累积
     方案：在 gst_element_set_state(NULL) 前手动 unref 所有 source
     预防：后续所有 GstPipeline 操作必须使用 RAII wrapper
  ✅ wiki/bugs/bug-20260428-rtsp-memory-leak.md 已更新
  ✅ wiki/lessons/ 新增 [[lesson-gst-raii]] — 发现模式：3个bug有共同根因
```

**关键**：AI 修代码前会**强制先查 wiki**，不会再犯同样的错：

```
你：「帮我修复 RTSP 连接断开的问题」

AI：
  🔍 查了 wiki/bugs/ → 发现 [[bug-20260428-rtsp-memory-leak]]，关联教训 [[lesson-gst-raii]]
  📖 教训规定：所有 GstPipeline 操作必须使用 RAII wrapper
  → 按已有教训修复，不会重蹈覆辙
```

### 🎯 开始新 Feature

```
你：「我要加 WebRTC H.265 支持，打通 MediaMTX → WebRTC → H.265 链路」

AI：
  📋 已创建任务规划：
     wiki/planning/TASKS/2026-04-28-webrtc-h265/
       ├── task_plan.md    ← 目标、范围、步骤、验收标准
       ├── findings.md     ← 技术研究发现
       └── progress.md     ← 进度追踪
  ✅ Feature SSoT 已更新
```

AI 执行时会**自动遵守 Planning Loop**：
- 每阶段前重读 `task_plan.md` 对齐目标
- 每阶段后更新 `progress.md`
- 研究发现写入 `findings.md`，不丢中间产物

### ⏰ 长程任务（持续几小时）

```
你：「这个重构任务可能要几小时，帮我建个执行合同」

AI：
  📜 Long-Running Task Contract 已生成：
     Goal：重构认证模块为中间件模式
     Scope：只改 auth/ 和 middleware/，不动路由层
     Review Loop：implement → test → self-review → fix
     Stop Condition：所有 L3 回归面通过 + walkthrough 完成
     Deliverables：重构后代码 + 更新的测试 + walkthrough
```

核心原则：**开放执行，封闭验收；多轮证据，不靠感觉。**

### 🧪 回归保障

AI 知道改了什么该跑什么测试：

```
你：「我改了 API 路由层」

AI：
  ⚡ 根据 Cadence Ledger，需触发：
     RG-001（基础连通性）✅ 通过
     RG-003（路由匹配）  ✅ 通过
  📊 Evidence Depth：L2（本地冒烟）
```

Evidence Depth 五级制：

| 层级 | 名称 | 含义 |
|------|------|------|
| L1 | tests | 只有单元测试 |
| L2 | local_smoke | 本地冒烟通过 |
| L3 | live_e2e | 真实环境端到端 |
| L4 | browser_human_proxy | 浏览器模拟真人 |
| L5 | hard_gate | 结构化判定 + 非零退出 |

### ✅ Wave 收口

```
你：「这个 feature 做完了，帮我写 walkthrough」

AI：
  ✅ Walkthrough 已生成：wiki/walkthroughs/2026-04-28-webrtc-h265.md
     范围：MediaMTX 配置 + 前端播放器适配
     关键决策：选 Jessibuca 而非 video.js（WASM H.265 支持）
     验证：L3 live_e2e 通过
     Residual：Safari 兼容性待后续处理
```

没有 walkthrough 的 wave 视为未完成。下一篇 walkthrough 是下一轮 AI 的输入。

### 🔍 自检与图谱

```
你：「检查一下 wiki 有没有问题」

AI：
  🔍 断链检查：0 处
  🔍 孤立页面：1 个 — wiki/decisions/adr-20260428-x.md（未被引用）
  🚨 未关闭高优 bug：1 个 — bug-20260428-xxx.md（P0，in-progress）
  📊 总页面：23 | bugs：5 | lessons：3 | 规划：8
```

```
你：「生成知识图谱」

AI：✅ 已生成 graph/graph.html，用浏览器打开可查看交互式图谱
```

---

## 对话速查表

| 你说 | AI 做什么 |
|------|----------|
| 「初始化项目 wiki」 | 执行 12 Phase SOP，生成完整目录 + AGENTS.md |
| 「记录一个 bug：XXX」 | 创建 raw bug → ingest → 生成 wiki 页面 |
| 「修好了，记录一下」 | bug-fix-record：根因 + 方案 + 预防 + 模式识别 |
| 「开始做 XXX feature」 | 创建 Planning Loop 三件套 + 更新 Feature SSoT |
| 「这是个长任务，建合同」 | 生成 Long-Running Task Contract |
| 「改了 XXX，该跑什么回归」 | Cadence Ledger 匹配 + 执行回归 + 记录 Evidence Depth |
| 「这个 wave 完成了」 | 写 Walkthrough + 回写 SSoT |
| 「检查 wiki」 | lint：断链 + 孤立页面 + 未关闭高优 bug |
| 「生成图谱」 | build-graph → graph/graph.html |
| 「ingest raw/xxx」 | 手动指定 raw 文件摄入 |

---

## 与各种 AI 工具配合

### OpenClaw

安装后 AI 自动读取 SKILL.md，项目初始化后自动读取 AGENTS.md。直接说话就行。

### OpenCode

OpenCode 自动识别 skills 目录下的 SKILL.md。

### Claude Code

Claude Code 没有 skills 目录机制，但它会自动读取项目根目录的 `CLAUDE.md`。初始化项目时，coding-wiki skill 会自动生成 `CLAUDE.md`（内容与 `AGENTS.md` 相同），所以功能完全可用。

### Cursor / Copilot / Aider

这些工具都能识别项目根目录的规则文件（AGENTS.md / .cursorrules / .github/copilot-instructions.md）。初始化时按需生成。

### 原则

**不管用什么工具，交互方式都一样——说话，别敲命令。** 脚本只是 AI 内部的实现细节，你不需要关心。

---

## Obsidian 联动

```
你：「把 wiki 链接到我的 Obsidian」
AI：[创建符号链接]
```

或手动：

```bash
ln -sfn /path/to/project/wiki ~/ObsidianVault/coding-wiki
```

Obsidian 中可用：
- **Graph View** — 需求/bug/决策/任务的关系网络
- **Dataview** — 查询未关闭 bug、进行中任务
- **Backlinks** — 查看某个页面被哪些页面引用

---

## 内部机制（选读）

以下是 AI 内部的实现细节，你不需要手动执行，但了解原理有助于更好地使用。

### Raw → Wiki 转换管道

```
raw/bugs/xxx.md        → wiki/bugs/bug-YYYYMMDD-xxx.md
raw/requirements/xxx.md → wiki/requirements/req-YYYYMMDD-xxx.md
raw/decisions/xxx.md   → wiki/decisions/adr-YYYYMMDD-xxx.md
raw/meetings/xxx.md    → wiki/meetings/mtg-YYYYMMDD-xxx.md
raw/planning/xxx.md    → wiki/planning/TASKS/YYYY-MM-DD-xxx/（三件套）
raw/test-qa/xxx.md     → wiki/test-qa/xxx.md
raw/walkthroughs/xxx.md → wiki/walkthroughs/xxx.md
```

### Bug 修复记录模板

| 字段 | 作用 |
|------|------|
| 5 Why 根因分析 | 追问到底为什么发生，而非表面原因 |
| 修复方案 | 具体怎么修的，为什么不选其他方案 |
| 为什么会发生 | 系统性原因，而非偶然 |
| 预防措施 | 下次怎么避免同类问题 |
| 模式识别 | 是否违反已有 lesson 规范；3+bug 同根因 → 自动创建 lesson |

### Planning Loop 三件套

```
wiki/planning/TASKS/<日期-任务名>/
├── task_plan.md     ← 锚点：目标、范围、步骤、验收标准
├── findings.md      ← 研究：技术发现、方案比较
└── progress.md      ← 追踪：每阶段做了什么、验证了什么
```

为什么有效：AI 上下文窗口有限，`task_plan` 是唯一稳定锚点；`progress.md` 让下个 session 的 AI 快速接上；`findings.md` 避免重复研究。

### SSoT 双轨治理

| SSoT | 管什么 | 位置 |
|------|--------|------|
| Feature SSoT | 哪些 feature 在做、做到哪了 | `wiki/planning/Feature-SSoT.md` |
| Regression SSoT | 哪些回归面存在、证据深度 | `wiki/test-qa/Regression-SSoT.md` |

开始任务前读 SSoT，完成后回写 SSoT。两者互相引用但不互相吞并。

### 12 Phase 初始化 SOP

| Phase | 做什么 | 产出 |
|-------|--------|------|
| 1 | 项目诊断 | Onboarding Audit 表格 |
| 2 | 确认规模 | Lite / Standard / Full |
| 3 | 搭建目录 | raw/ + wiki/ 完整结构 |
| 4 | 生成规则 | AGENTS.md + CLAUDE.md（含 Task-Type Reading Matrix） |
| 5 | 生成标准 | wiki/reference/ 参考文件 |
| 6 | 初始化规划 | Planning Loop 三件套模板 |
| 7 | 长程协议 | Long-Running Task Contract 模板 |
| 8 | SSoT 治理 | Feature SSoT + Regression SSoT |
| 9 | 回归体系 | Regression SSoT + Cadence Ledger |
| 10 | 收口流程 | Walkthrough 模板 |
| 11 | 并行规范 | Worktree 标准 |
| 12 | 启动摘要 | Bootstrap Summary |

---

## 适合什么项目

| 场景 | 适合度 | 原因 |
|------|--------|------|
| AI 辅助开发的中大型项目 | ⭐⭐⭐⭐⭐ | 正是为这种场景设计 |
| 经常踩重复坑的项目 | ⭐⭐⭐⭐⭐ | bug-fix-record + lessons 直接解决 |
| AI 长时间执行复杂任务 | ⭐⭐⭐⭐⭐ | Planning Loop + 合同防跑偏 |
| 多人 + 多 Agent 协作 | ⭐⭐⭐⭐ | SSoT 双轨制保证一致 |
| 小型脚本/一次性项目 | ⭐⭐ | 用 lite 模式 |
| 纯人工不用 AI | ⭐ | 文档是给 Agent 看的 |

---

## 设计理念

**对话优先。** 你只需要说话，AI 处理一切。脚本、模板、目录结构都是 AI 的内部实现细节。

**文档写给 Agent 看。** 格式优先考虑 AI 可解析性，人类可读性是副产品。

**上下文越准越好。** AGENTS.md 的 Task-Type Reading Matrix 精确告诉 AI 做什么任务该读什么文件。

**强制流程优于口头约定。** 每个步骤都是 AI 可自主执行的，不依赖"你记得要做 X"。

**单元测试只是底线。** L1 只能说明代码能编译，真正的保障需要多层 Evidence Depth。

**长程任务先设计合同。** 开放执行，封闭验收；多轮证据，不靠感觉。

---

## License

MIT