核心用法
AgentLens 是一套面向大型代码库的层级式文档导航体系。用户始终从 .agentlens/INDEX.md 项目总览出发，按需下钻至三级文档：L0 级 INDEX.md 提供项目全貌与模块清单；L1 级包含 MODULE.md（模块详情）、outline.md（大文件符号索引）、memory.md（TODO/警告/业务规则）、imports.md（文件依赖关系）；L2 级 files/{slug}.md 针对复杂文件提供深度说明。
最佳实践强调"不直接阅读源码"原则：先通过 outline.md 定位目标符号，再精准阅读对应代码段；修改前必查 memory.md 规避已知陷阱；文档过期时使用 agentlens 命令重新生成。
显著优点
- 层级化索引：将海量代码转化为可快速检索的结构化地图，显著降低认知负荷
- 精准定位：
outline.md解决"大文件找函数"痛点，memory.md沉淀团队经验 - 非侵入式：作为文档层叠加于现有代码库，无需改造既有架构
- AI原生设计：文档格式针对大模型上下文优化，支持自动化生成与更新
潜在局限
- 维护成本：文档与代码同步依赖人工或工具触发，存在过期风险
- 覆盖盲区：默认结构可能遗漏动态元编程、复杂宏生成代码
- 工具依赖：需安装
agentlensCLI 生成文档，增加环境配置步骤 - 学习曲线：开发者需适应"先查文档再读代码"的新工作流
适合人群
- 新成员快速 onboarding 大型/遗留项目
- 跨模块调试时需快速理解陌生子系统的开发者
- 希望沉淀 TODO、业务规则等隐性知识的团队
常规风险
| 风险类型 | 说明 |
|---------|------|
| 文档过时 | 代码变更后未重跑 `agentlens`，导致索引失效 |
| 过度依赖 | 忽视直接阅读源码，漏掉文档未覆盖的边缘逻辑 |
| 敏感信息泄露 | `memory.md` 可能记录内部 TODO 或安全警告，需注意访问控制 |