lat.md：把任意文件夹变成AI可查询的验证知识图谱
当文档跟不上代码
AI编程助手越来越强，但它们的最大瓶颈不是模型能力——而是看不到全局。
一个Claude Code的上下文窗口再大，也不可能一次读懂上千个文件的项目。更糟糕的是，你给AI的那份README，很可能已经过时了。
传统文档有三个死穴：
- 太长——单个README文件动辄几千行，AI根本读不完
- 过期——代码改了，文档没改，没人知道
- 缺上下文——只说了”做了什么”，没说”为什么这么做”
lat.md（Agent Lattice）就是来干这个的。它把你项目的文件夹变成一张可查询、可验证的知识图谱。每个文档节点都和代码里的具体实现挂钩，而且有自动检查机制确保它们永远同步。
lat.md 是什么
lat.md 是一个开源工具，专门给AI编程助手（Claude Code、Cursor、Aider等）提供项目的”地图”。它不是普通的文档生成器，而是一个带引用完整性的知识图谱系统。
项目地址：https://github.com/lat-md/lat.md
作者 Ana Bildea 之前写过 Graphify——另一种知识图谱工具。lat.md 和 Graphify 的区别在于：
- Graphify：擅长从代码、文档甚至音视频中做高层提取，减少71.5倍的Token消耗
- lat.md：更强调引用完整性，确保每个文档概念都和实际代码同步，适合需要严格验证的开发流程
五步上手：从安装到自动验证
第一步：安装和初始化
一行命令的事：
npx lat.md init
这个命令会做三件事：
- 询问你用的AI工具（Claude还是Cursor）
- 在你的项目里创建一个特殊的”地图”文件夹
- 给AI工具添加指令，告诉它们优先看地图而不是从头读文件
第二步：扫描代码
npx lat.md scan
这一步完全在本地执行，代码不会上传到任何服务器。lat.md 支持20多种编程语言，能自动识别：
- 函数和类定义
- 模块之间的依赖关系
- 核心代码结构
因为是自动扫描，地图永远和你的实际代码保持一致。
第三步：连接文档和代码
这是 lat.md 的核心能力——把文档和代码绑在一起。
你可以在Markdown文档里用特殊标记指向代码：
## 用户认证模块
<!-- @lat:src/auth/login.ts -->
登录流程使用OAuth 2.0，token存储在Redis中，有效期24小时。
也可以在代码里加注释指向文档：
// @lat:doc:/docs/auth.md
// 参考认证文档了解完整的安全策略
async function login(email: string, password: string) {
// ...
}
然后运行检查命令：
npx lat.md check
如果有链接断了，或者某段代码没有对应的文档，这个命令会立刻报错。
第四步：”摘要优先”规则
lat.md 强制要求每个文档章节都以一段简短的摘要开头，不超过2-3句话。
这不是形式主义。AI在搜索地图时，会先扫一遍摘要来判断哪些部分相关。没有摘要的章节，check命令直接报错。
这个设计让整个知识库对人和AI都友好——人类读摘要把握全局，AI凭摘要快速定位。
第五步：自动化检查
文档被忽视的最大原因是什么？维护成本。没人有精力每天手动检查文档是不是还准确。
lat.md 把文档检查嵌入了开发流程：
# 在git hooks里加一行
# pre-commit时自动检查
npx lat.md check --strict
如果设置成pre-commit hook，每次提交代码时自动检查链接完整性。有断链？提交被阻止。这样你的知识地图就永远不会”过期”。
更深入的使用场景
大型项目的情报中心
当项目有几千个文件、多个团队协作时，没有人能记住所有细节。lat.md 的地图就成了团队的”情报中心”：
- 新成员入职：直接看地图，而不是翻遍整个代码库
- 跨团队协作：API接口在哪里定义、数据库表结构是什么，地图上一目了然
- 技术决策记录：为什么选择这个方案，约束条件是什么，写在地图里永远不丢
AI驱动的代码审查
结合Claude Code或Cursor，lat.md 能让AI做更精准的代码审查：
claude "根据项目地图检查这个PR是否符合架构规范"
AI有了完整的上下文地图，可以判断新代码是否违反了既定的设计决策、是否和现有模块产生了冲突。
增量式文档建设
lat.md 不要求一口气写完所有文档。做法是：
- 先给核心模块写地图——用户认证、数据存储、API路由
- 运行 setup，让AI辅助写第一批笔记
- 开启自动检查
- 每周补充一到两个模块
这种方式成本很低，但效果立竿见影。
技术实现
lat.md 的技术栈很轻量：
- 核心：TypeScript，Node.js运行
- 解析器：支持20+语言的AST解析（Tree-sitter）
- 存储：本地文件系统，Markdown + YAML
- 检查引擎：自定义的引用完整性验证器
- AI集成：通过CLAUDE.md、.cursorrules等配置文件对接
// lat.md 内部的数据结构示例
interface KnowledgeNode {
id: string;
type: 'module' | 'function' | 'class' | 'concept';
summary: string;
content: string;
codeRefs: CodeReference[];
docRefs: DocReference[];
lastVerified: Date;
}
整个工具不需要数据库，不需要云服务，所有数据都存在你的项目文件夹里。这保证了隐私和可移植性。
适用场景和限制
lat.md 最适合：
- 中大型项目（100+文件）：小项目可能不需要这么重的文档管理
- 多团队协作：需要统一的文档规范和验证
- AI深度使用：重度依赖Claude Code、Cursor等工具的团队
- 合规需求：需要证明文档和代码一致的场景（审计、监管）
目前已知的限制：
- 极端复杂的代码偶有解析问题（但团队的迭代速度很快）
- 不支持闭源项目（需要在项目内建立open目录）
和竞品的对比
这个领域还有几个工具值得了解：
| 工具 | 核心能力 | 适合场景 | 验证机制 |
|---|---|---|---|
| lat.md | 引用完整性知识图谱 | 需要严格验证的团队 | 内置check命令 |
| Graphify | 高层知识提取 | 快速理解大型代码库 | 无自动验证 |
| Mermaid | 图表生成 | 可视化架构 | 无 |
| 传统Wiki | 手动文档 | 团队知识库 | 无 |
lat.md 的核心差异在于：它不只帮你写文档，它确保文档不会过期。
总结
如果你遇到过这些问题，lat.md 值得一试：
- AI助手总是写不出符合项目架构的代码
- 文档写了一堆但没人看、没人更新
- 新成员入职要花两周才能搞清代码结构
- 代码审查时发现新代码不符合原本的设计决策
地图是AI理解你项目的方式。其他都只是猜测。
lat.md 的核心思想很简单：把笔记和代码直接挂钩，并且用自动化检查保证它们永远同步。这就让AI工具不再是”猜”，而是真正”知道”你的项目在做什么。
开始用：
npx lat.md init
在任意项目文件夹里跑这行命令，把自己从”搜索引擎”变成”地图导航员”。