用途:为代码库生成高质量的 ARCHITECTURE.md,帮助新人建立代码库心智地图。其出发点是:贡献者最大的瓶颈不是写代码,而是判断该在哪里改代码。
主要能力与原则:文档应简短稳定,只描述不易频繁变化的内容,不随代码同步,每年回顾几次;先讲鸟瞰视角,从要解决的问题而非解决方案开始;以代码地图(codemap)代替散文,回答每个模块“做 X 的东西在哪”“这个模块做什么”;只命名重要文件、模块、类型,不做超链接(链接会失效),鼓励符号搜索;明确写出不变量,尤其是“刻意缺失”的部分;标记 API 边界;最后处理横切关注点(错误处理、测试、配置等)。
使用方式:先探索代码库,读取 README、package.json/Cargo.toml/pyproject.toml 了解项目目的,运行 tree -L 2 -d 查看目录结构,识别入口点,阅读模块边界处的关键文件。然后梳理架构:要解决的问题、粗粒度模块、数据流、API 边界、架构不变量、横切关注点。最后按模板撰写,多数项目控制在约 300 行以内。模板包含标题、鸟瞰视角、代码地图(用 ### path/to/module/ 标题,配 Boundary: 与 Invariant: 加粗标注)、横切关注点(错误处理、测试等)。
适用场景:需要为项目补充架构说明、帮助新成员快速定位改动位置时。
限制:不写单个模块的实现细节、不链接具体文件或行、不写随常规 PR 变化的内容、不写详尽 API 文档、不写安装说明(属 README)和贡献指南(属 CONTRIBUTING.md)。资料未提供具体安装命令、收费或平台信息。