用LLM管理安全开发规范：一次llm-wiki实践

发表于 阅读次数：

最近在整理团队的安全开发规范时，遇到了一个老问题：安全规范文档越积越多，但真正用的时候却找不到。每次新人入职，都要翻遍各种文档才能拼凑出完整的安全规范；每次出安全故障，事后总结的经验也散落在各处，下次遇到类似问题还得重新排查。

我试过用Confluence、Notion、甚至Git仓库的README来管理，但效果都不理想。直到看到了Karpathy提的llm-wiki思路，才觉得这可能是个突破口。

Karpathy的llm-wiki是什么？

Karpathy在Gist里提了个想法：让LLM维护一个Wiki中间层。原话是”the wiki is a persistent, compounding artifact”——这个Wiki层就像个编译器，把原始文档编译成结构化数据，这样LLM每次回答问题时就不用从头在原始文档里”找”信息，直接查Wiki就行。

我觉得这个思路特别妙。传统文档管理是”存”和”找”，而llm-wiki是”编译”和”查询”。原始文档可能很乱、有重复、甚至有矛盾，但Wiki层是干净、结构化、有交叉引用的。

举个例子：我们团队有十几份安全开发规范文档，从输入验证到渗透测试都有，还有近十份安全故障复盘报告。这些文档格式不一，有的在Word里，有的在Markdown里，有的甚至只是Slack聊天记录。如果让LLM直接处理这些原始材料，效率会很低。但如果先”编译”成Wiki，效果就完全不一样了。

我的实现过程

第一步：生成CLAUDE.md

我首先把Karpathy的Gist链接丢给Claude，让它基于这个思路生成一份CLAUDE.md文件。这个文件相当于给LLM的”操作手册”，告诉它如何维护Wiki。

生成的CLAUDE.md包含了几个关键部分：

  • 三层架构说明（raw → wiki → output）
  • Wiki页面规范（frontmatter格式、交叉引用规则）
  • 摄入工作流（如何处理新素材）
  • 查询工作流（如何回答用户问题）
  • Lint检查（如何保证Wiki健康）

实际用下来，我发现模型生成的结果基本可用，没有做太多微调。只是另外让AI生成了output层，用于存放最终的规范文档。这样三层架构就完整了：raw放原始素材，wiki放结构化Wiki，output放最终输出。

第二步：收集和整理原始素材

这是最耗时的一步。我把散落在各处的安全开发规范文档和故障案例都收集起来，统一放到raw/sources/目录下。为了保持原貌，我没有修改这些文件的内容，也没有统一格式——PDF、Word、PPT、Markdown等各种格式直接放到raw层就行，模型都可以处理。

具体来说，我收集了：

  • 十几份安全开发规范文档：涵盖输入验证、SQL注入防护、XSS防护、CSRF防护、敏感数据保护、日志安全等
  • 近十份安全故障复盘报告：包括SQL注入漏洞、越权访问、敏感信息泄露、会话劫持等真实案例
  • 几份安全架构方案文档：涉及零信任架构、安全编码指南、渗透测试流程等

这些素材质量参差不齐。有的写得很规范，有清晰的标题和列表；有的就是随手记的笔记，甚至还有截图。但没关系，llm-wiki的妙处就在于它能处理这种”脏数据”。

第三步：让LLM生成Wiki层

有了CLAUDE.md和原始素材，就可以让LLM开始工作了。我这里用的是Claude，主要是因为它的上下文窗口足够大，能一次性处理较多内容。

具体操作是这样的：

  1. 把CLAUDE.md作为系统提示词
  2. 告诉LLM：”请按照CLAUDE.md中的规范，处理raw/sources/目录下的所有素材，生成wiki层”
  3. LLM会依次读取每个原始文件，提取关键信息，生成对应的Wiki页面

这个过程不是一次就能完成的。LLM生成的初版Wiki会有一些问题：

  • 交叉引用不够充分
  • 有些概念没有被提取成独立页面
  • 页面之间的逻辑关系不够清晰

所以需要多轮迭代。我会检查生成的Wiki，指出问题，让LLM修正。比如：
“这个故障案例里提到了’连接池配置不当’，但为什么没有对应的concept页面？请创建一个[[connection-pool-best-practices]]页面，并在故障案例里引用它。”

经过5-6轮迭代，Wiki层才逐渐成型。

第四步：生成最终规范文档

Wiki层准备好后，就可以生成最终的规范文档了。我让LLM基于Wiki层，生成一份面向开发者的、可直接阅读的规范文档。

这里有个设计决策：最终文档是放在output/目录下，而不是直接修改原始素材。这样保持了三层架构的清晰性：

  • raw/：原始素材，不可修改
  • wiki/：结构化Wiki，LLM维护
  • output/：最终输出，人类阅读

生成的规范文档有几个特点：

  1. 每个规范条目都有”为什么”——不只是说”要这样做”，还解释”为什么要这样做”
  2. 相关的故障案例会作为”反面教材”链接在旁边
  3. 有交叉引用，比如”数据库连接池配置”会链接到”连接池最佳实践”这个concept页面

实际效果

阅读体验

最终的规范文档可以直接用Obsidian打开阅读。因为是Markdown格式，支持：

  • 代码块高亮
  • 内部链接跳转（点击就能跳转到相关概念或故障案例）
  • 标签筛选（比如筛选所有#安全相关的规范）

更重要的是，每条安全规范都关联着真实的故障案例。比如在”SQL注入防护”这条规范旁边，就链接着[[sql-injection-vulnerability-incident]]这个故障案例，详细描述了漏洞是怎么产生的、造成了什么影响、怎么修复的。这样开发者不仅能知道”要怎么做”，还能看到”不这么做会出什么问题”。

比起以前散落在各处的文档，阅读体验好了不止一个量级。

LLM问答

更强大的是LLM问答能力。因为有了Wiki层，LLM回答问题时特别准。比如我问：
“数据库批量更新时要注意什么？”

LLM会：

  1. 先在Wiki里找到[[batch-operation-security]]这个concept页面
  2. 结合[[sql-injection-batch-incident]]这个故障案例
  3. 给出具体的建议：必须使用参数化查询、禁止字符串拼接SQL、批量操作要有事务控制、超大批次要分页处理等
  4. 还会解释为什么：因为批量操作一旦出问题，影响范围是单条操作的N倍

再比如问：”用户上传文件怎么处理才安全？”

LLM会：

  1. 找到[[file-upload-security]]这个concept页面
  2. 结合[[malicious-file-upload-incident]]这个故障案例
  3. 给出具体建议：文件类型白名单校验、文件内容检测、重命名存储、限制文件大小、隔离存储等

这比让LLM在十几份原始文档里”找”答案要靠谱得多。

持续更新

最让我满意的是更新机制。当有新的规范文档或故障报告时，我只需要：

  1. 把新文件放到raw/sources/目录下
  2. 告诉LLM：”有新素材需要摄入”
  3. LLM会自动更新Wiki层和规范文档

比如上周我们出了个新的安全故障：因为用户输入未过滤导致XSS漏洞。我把故障报告放到raw目录后，LLM自动：

  1. 创建了[[xss-user-input-incident]]这个故障案例页面
  2. 更新了[[input-validation-security]]这个concept页面，补充了XSS相关的注意事项
  3. 在规范文档的”输入验证规范”章节增加了相关条目

遇到的问题和解决方案

问题1：LLM生成的Wiki质量不稳定

刚开始时，LLM生成的Wiki质量波动很大。有时能很好地提取关键信息，有时会漏掉重要内容。

解决方案：我细化了CLAUDE.md里的Wiki页面规范。比如要求每个页面必须有：

  • Summary行：一句话描述核心内容
  • Tags行：用#标签标记主题
  • 明确的页面类型（concept/entity/source/comparison）

对于安全故障案例，还要求包含：漏洞类型、攻击向量、影响范围、修复方案、预防措施。这样LLM就有更清晰的指导，生成质量稳定了很多。

问题2：交叉引用经常断裂

Wiki的核心价值在于交叉引用，但LLM经常创建单向链接，或者链接到不存在的页面。

解决方案：在CLAUDE.md里强化了交叉引用规则：

  1. 必须双向链接：如果A页面引用了[[B]]，那么B页面也必须引用[[A]]
  2. frontmatter里的related字段必须和正文里的[[wiki-link]]一致
  3. 只能引用已存在的页面，需要先创建再引用

我还加了Lint检查，定期检查断裂链接和孤儿页面。

问题3：处理非结构化素材效率低

有些原始素材质量很差，比如截图、手写笔记、甚至是Slack聊天记录的导出。LLM处理这些素材时效率很低。

解决方案：对于这类素材，我会先手动整理成结构化的Markdown，再交给LLM处理。虽然增加了前期工作量，但保证了最终质量。

一些经验教训

  1. 不要追求一步到位。llm-wiki是个迭代过程。第一版Wiki肯定不完美，但可以通过持续迭代改进。

  2. CLAUDE.md要不断优化。随着使用，你会发现CLAUDE.md里缺失的规则。比如我后来加了”安全故障案例必须包含：漏洞类型、攻击向量、影响范围、修复方案、预防措施”这样的结构化要求。

  3. 保持三层架构的纯净。raw/就是raw/，不要修改；wiki/由LLM维护；output/面向人类。混在一起会越来越乱。

  4. 定期做健康检查。我会每周跑一次Lint，检查断裂链接、孤儿页面、单向链接等问题。发现问题及时修复。

  5. 接受不完美。LLM生成的Wiki不会100%准确，会有遗漏和错误。但相比完全靠人工维护，已经好太多了。

总结

用llm-wiki管理安全开发规范，本质上是把”文档管理”变成了”知识工程”。原始文档是”原材料”，Wiki是”半成品”，规范文档是”成品”。LLM在这个过程中充当了”编译器”和”维护者”的角色。

这个方法最大的价值是可持续性。传统的文档管理，时间一长就会荒废，因为维护成本太高。而llm-wiki把维护成本转移给了LLM，人类只需要：

  1. 提供原始素材（这个避免不了）
  2. 检查和修正LLM的工作（比从头写轻松多了）
  3. 使用最终产出（享受成果）

如果你也在为安全开发规范的管理头疼，不妨试试这个思路。不用完全照搬我的实现，关键是理解”Wiki中间层”这个核心理念。至于具体用什么工具、怎么组织目录，都可以根据实际情况调整。

毕竟，工具是为人服务的，不是吗？

原文地址: http://lichuanyang.top/posts/88001/