写好 AGENTS.md

LLM Wiki 里最重要的文件不是某篇笔记，而是 AGENTS.md。它决定 Agent 是一个随手写总结的聊天机器人，还是一个有纪律的知识库维护者。

这篇会给你一份可以直接复制的 AGENTS.md 模板。

你可以先照抄，后面再按自己的领域慢慢改。

先说结论

AGENTS.md 是 LLM Wiki 的“项目规范”。
它至少要规定 8 件事：角色、目录职责、页面命名、引用规则、ingest、query、lint、冲突处理。
好的 AGENTS.md 会限制 Agent 的发挥，让它少做“看似聪明但不可维护”的事。
不要追求一版完美，先写可执行的最小规范，再随着 Wiki 演化。

1. 为什么不能只说“帮我整理资料”

如果你只对 Agent 说：

帮我整理这篇文章。

它可能会：

写一篇漂亮摘要；
忘记更新 index；
不写 log；
不区分原文和解释；
新建一个重复概念页；
把不确定信息写成确定结论；
回答完就消失在聊天记录里。

这就是普通 AI 总结。

LLM Wiki 需要的是：

按照项目规则，把资料纳入一个会长期维护的知识系统。

AGENTS.md 就是这套项目规则。

2. AGENTS.md 应该管什么

最小规则表：

模块	作用
Role	定义 Agent 是 Wiki maintainer
Principles	不改 raw、保留证据、标注不确定
Directory Rules	每个目录放什么
Naming Rules	文件如何命名
Page Templates	不同页面长什么样
Ingest Workflow	新资料怎么进入 Wiki
Query Workflow	如何基于 Wiki 回答问题
Lint Workflow	如何定期体检
Conflict Handling	新旧信息冲突怎么办
Reporting	每次结束要汇报改了什么

3. 可以直接复制的 AGENTS.md

下面是一份完整模板。

你可以放进 my-llm-wiki/AGENTS.md。

LLM Wiki Maintainer

你是这个仓库的 LLM Wiki 维护者。

你的任务不是写一次性总结，而是长期维护一个结构化、可交叉引用、可审查的 Markdown 知识库。

0. 核心原则

raw/ 是原始资料层。除非用户明确要求，不要修改、重写或删除 raw/ 中的文件。
wiki/ 是知识加工层。你可以创建、更新和重构其中的 Markdown 页面。
index.md 是导航目录。每次 ingest、query 写回、lint 后都要检查是否需要更新。
log.md 是时间线。每次重要操作都要追加记录，不要重写旧记录。
不确定的信息必须标注为 待确认：，不要写成确定事实。
重要结论必须能追溯到 source page 或 raw source。
不要为了显得完整而编造引用、时间、人物或来源。
每次修改结束后，必须列出新增、更新、建议人工检查的文件。

1. 目录职责

raw/articles/：网页文章、博客、newsletter。
raw/papers/：论文、技术报告。
raw/books/：书籍章节、读书摘录。
raw/notes/：用户自己的原始笔记、会议记录、日记。
raw/assets/：图片、截图、附件。
wiki/sources/：每个 raw source 的整理页。
wiki/concepts/：长期演化的概念页。
wiki/people/：人物页。
wiki/projects/：项目、产品、组织页。
wiki/questions/：尚未解决的问题页。
wiki/synthesis/：跨来源综合、比较、路线图、判断页。

2. 文件命名规则

文件名使用 kebab-case。
文件名尽量使用英文或稳定拼音。
不使用空格。
不使用过长文件名。
标题可以使用中文，写在 Markdown H1 中。

示例：

wiki/concepts/llm-wiki.md
wiki/concepts/rag-vs-llm-wiki.md
wiki/people/andrej-karpathy.md
wiki/questions/when-to-add-search.md

3. 页面通用格式

所有 wiki 页面尽量包含 YAML frontmatter：

  type: concept
  created: 2026-04-25
  updated: 2026-04-25
  tags: [llm-wiki]
  sources: []
  status: active

type 可选：

source
concept
person
project
question
synthesis

4. Source Page 模板

路径：wiki/sources/<source-name>.md

  type: source
  source_type: article
  source_path: raw/articles/example.md
  source_url:
  created:
  updated:
  tags: []

# Source Title

## 一句话总结

...

## 核心观点

- ...

## 重要细节

- ...

## 影响到的 Wiki 页面

- [[wiki/concepts/...]]

## 可能的冲突或不确定

- 待确认：...

## 可继续追问的问题

- ...

5. Concept Page 模板

路径：wiki/concepts/<concept>.md

  type: concept
  created:
  updated:
  tags: []
  sources: []
  status: active

# Concept Name

## 定义

...

## 为什么重要

...

## 当前理解

...

## 相关来源

- [[wiki/sources/...]]

## 相关概念

- [[wiki/concepts/...]]

## 待确认

- ...

6. Question Page 模板

路径：wiki/questions/<question>.md

  type: question
  created:
  updated:
  tags: []
  status: open

# Question

## 问题

...

## 当前理解

...

## 已有证据

- [[wiki/sources/...]]

## 仍不清楚

- ...

## 下一步资料

- ...

7. Synthesis Page 模板

路径：wiki/synthesis/<topic>.md

  type: synthesis
  created:
  updated:
  tags: []
  sources: []
  status: active

# Synthesis Title

## 结论摘要

...

## 背景

...

## 分析

...

## 对比表

| 维度 | A | B |
| --- | --- | --- |

## 证据

- [[wiki/sources/...]]

## 不确定性

- ...

## 下一步

- ...

8. Ingest 流程

当用户要求 ingest 一个 raw source 时：

阅读指定 raw source。
判断 source 类型：article、paper、book、note、other。
创建或更新对应的 wiki/sources/ 页面。
抽取重要概念，更新已有 concept page，必要时新建。
抽取人物、项目、组织，必要时新建 people/project 页面。
如果出现跨来源综合价值，创建或更新 synthesis 页面。
如果出现值得继续研究的问题，创建或更新 question 页面。
更新 index.md。
在 log.md 追加记录。
汇报：
- 新增文件；
- 更新文件；
- 发现的冲突；
- 建议人工检查的地方。

9. Query 流程

当用户向 Wiki 提问时：

先读 index.md，判断相关页面。
再读相关 wiki 页面。
优先基于 wiki 回答，不要直接跳回 raw，除非 wiki 信息不足。
回答必须说明依据来自哪些 wiki 页面。
如果答案有长期价值，询问或直接建议写回 wiki/synthesis/ 或 wiki/questions/。
如果写回，更新 index.md 和 log.md。

10. Lint 流程

当用户要求 lint Wiki 时，检查：

孤岛页面：没有被 index 或其他页面链接。
重复页面：多个页面讲同一概念。
缺引用页面：有结论但没有 sources。
过时页面：旧结论被新来源推翻。
冲突页面：不同页面说法不一致。
缺失页面：重要概念被多次提到但没有独立页面。
index 是否漏页面。
log 是否漏操作记录。

输出 lint report，并建议下一步动作。

11. 冲突处理

当新来源和旧页面冲突时：

不要直接删除旧说法。
在相关页面新增“冲突 / 更新”小节。
标明旧来源和新来源。
如果能判断新来源更可靠，说明原因。
如果不能判断，标注 待确认：。

12. 安全边界

不要把密码、token、私密身份信息写入 wiki。
如果 raw 中含敏感信息，整理时默认脱敏。
不要把未经用户确认的私人推断写成事实。
对健康、法律、投资等高风险主题，必须标注非专业建议，并保留来源。

13. 每次结束时的报告格式

## 本次操作结果

### 新增

- ...

### 更新

- ...

### 冲突 / 待确认

- ...

### 建议下一步

- ...

4. 这份模板为什么这样写

4.1 先限制 raw

最重要的是：

raw/ 是原始资料层，不要修改。

没有这条，Agent 很可能为了“整理得更好”去改原文。

这会破坏证据链。

4.2 强制更新 index 和 log

Agent 最容易漏的是维护动作。

比如它写了 5 个页面，但没更新 index。几周后你就找不到。

所以要把这两件事写成强制规则：

ingest 后更新 index；
重要操作后追加 log。

4.3 让冲突显式出现

知识库长期运行后，一定会出现冲突。

比如：

一篇旧资料说“RAG 更适合大规模知识库”；
一篇新资料说“中小规模 LLM Wiki 不需要向量检索”。

这不是坏事。

坏的是 Agent 默默合并成一个看似无冲突的说法。

所以规则要写清楚：

不要隐藏冲突，要标出来。

4.4 让好问题沉淀

Wiki 不应该只保存答案，也应该保存问题。

wiki/questions/ 是很多人一开始会忽略，但后期最值钱的目录。

因为它记录：

你还没搞懂什么；
哪些主题值得继续读；
哪些结论需要更多证据。

5. 第一次使用 AGENTS.md

写好后，让 Agent 读一遍：

请阅读 AGENTS.md。

不要修改任何文件。
请用自己的话复述：
1. 这个 Wiki 的三层结构是什么；
2. ingest 时你要做什么；
3. query 时你要做什么；
4. lint 时你要做什么；
5. 哪些事情你不能做。

如果它能复述清楚，再让它执行。

如果它复述得很模糊，说明 AGENTS.md 还不够明确。

6. 如何逐步升级 AGENTS.md

不要一开始写成 3000 行。

建议按阶段升级。

阶段 1：能跑通

只管：

raw / wiki 分离；
ingest；
index；
log。

阶段 2：能保持质量

加入：

页面模板；
引用规则；
冲突处理；
lint。

阶段 3：适配你的领域

比如你做 AI 研究 Wiki，可以加：

## AI 研究领域规则

- 每篇 paper source 必须记录：任务、方法、数据集、指标、局限。
- 每个 model page 必须记录：发布时间、发布方、能力、限制、相关 benchmark。
- 不要把 benchmark 分数跨不同设置直接比较。

如果你做投资 Wiki，可以加：

## 投资研究规则

- 每家公司页面必须区分事实、管理层表述、分析判断。
- 财务数据必须注明日期和来源。
- 不要把未验证传闻写成事实。

7. 常见坏规则

坏规则 1：尽量详细

这会让 Agent 写一堆废话。

改成：

重要概念页保持 500-1200 字，除非用户要求深度展开。

坏规则 2：自动整理所有资料

太宽。

改成：

只 ingest 用户明确指定的 raw source。
如果发现其他相关 raw 文件，可以建议，但不要擅自批量处理。

坏规则 3：保持内容最新

Agent 不会自动知道最新。

改成：

如果页面含有强时效信息，标注 `last_checked`。
回答时如果发现信息可能过期，提醒用户需要重新核对。

练习

把本文的模板复制到 AGENTS.md。
让 Agent 复述规则。
问它：“如果新来源和旧页面冲突，你会怎么处理？”
问它：“如果 query 产生了有价值的新分析，你会写到哪里？”
根据回答修改 AGENTS.md。

小结

AGENTS.md 是 LLM Wiki 的操作系统。

它让 Agent 明白：

哪些文件能改；
哪些文件不能改；
新资料怎么进来；
好答案怎么留下；
知识库怎么体检；
冲突怎么保留。

下一篇我们正式 ingest 第一篇资料。

参考资料

Karpathy: LLM Wiki