Agentlens

核心用法

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原生设计：文档格式针对大模型上下文优化，支持自动化生成与更新

潜在局限

• 维护成本：文档与代码同步依赖人工或工具触发，存在过期风险
• 覆盖盲区：默认结构可能遗漏动态元编程、复杂宏生成代码
• 工具依赖：需安装 agentlens CLI 生成文档，增加环境配置步骤
• 学习曲线：开发者需适应"先查文档再读代码"的新工作流

适合人群

• 新成员快速 onboarding 大型/遗留项目
• 跨模块调试时需快速理解陌生子系统的开发者
• 希望沉淀 TODO、业务规则等隐性知识的团队

常规风险

| 风险类型 | 说明 |

|---------|------|

| 文档过时 | 代码变更后未重跑 `agentlens`，导致索引失效 |

| 过度依赖 | 忽视直接阅读源码，漏掉文档未覆盖的边缘逻辑 |

| 敏感信息泄露 | `memory.md` 可能记录内部 TODO 或安全警告，需注意访问控制 |

核心用法

AgentLens 是一套分层文档导航系统，专为大型代码库探索设计。用户通过预生成的 Markdown 文档树快速定位代码，无需直接阅读冗长源文件：

1. 入口索引 (.agentlens/INDEX.md)：项目全景图，列出所有模块
2. 模块层 (modules/{slug}/)：包含 MODULE.md（模块详情）、outline.md（符号索引）、memory.md（TODO/警告）、imports.md（依赖关系）
3. 文件层 (files/{slug}.md)：复杂文件的深度文档

标准导航流：INDEX.md → MODULE.md → outline/memory → 精准定位源文件片段

显著优点

• 高效检索：将"大海捞针"变为结构化查找，outline.md 直接定位大型文件中的函数/类
• 风险规避：memory.md 预存业务规则和修改警告，避免踩坑
• 零学习成本：纯 Markdown，任何编辑器可读
• 绝对安全：T-MD 分类（纯文档型），无可执行代码、无依赖、无网络通信

潜在局限

• 文档时效性：需手动运行 agentlens 命令重新生成，Stale 文档会误导
• 前置成本：项目需预先建立文档结构，不适合无文档的老项目
• 深度有限：仅提供导航指引，复杂逻辑仍需阅读源码
• 生态依赖：需配合 agentlens CLI 工具使用

适合人群

• 接手陌生大型项目的开发者
• 需要快速定位 TODO/遗留问题的维护工程师
• 代码审查者需理解模块边界场景
• 追求"安全零风险"工具的安全敏感团队

常规风险

除文档过期外几乎无风险。需注意：若 Skill 作者未来版本添加可执行代码，安全评级将改变，建议持续监控 CLS 认证状态。