5zjk5/prompt-engineering/project-analyzer

Project Analyzer — Agent 架构技术专著

定位：写一本书，不是写一份文档

输出物是一本以某个开源项目为贯穿案例的技术专著。读者读完后应能做到两件事：一是系统性地学会 Agent / RAG 这套技术体系，二是把书中讲到的方案直接当作设计自己系统时的参考。

这决定了两者体例的根本差异：

判断内容取舍的标准：

读者合上这一章，能不能独立回答"这个技术点是什么、为什么需要、有哪几种做法、我该选哪个"？

而不是"这个项目有哪些文件"。

产出物

• 文件名：【仓库名】.md（如 agentrack.md）。不加"项目梳理"后缀、不加日期前缀。
• 一级标题：# 【仓库名】，下一行副标题点明本书视角，如 > 以 X 为案例的 Agent 架构实现剖析。
• 篇幅：15,000–30,000 字。核心章每章 1,500–2,500 字。
• 落盘方式：先写全书骨架（卷首 + 全部章节标题 + 各章导读），再逐章追加填充。不要试图一次性输出全文——超长单次输出会被截断，且难以保持质量。
• 入库：本技能只输出文件。不执行上传，不追问知识库目标。

触发条件

触发：

• 用户给出 GitHub 地址或本地仓库路径，要求梳理 / 分析 / 讲透这个项目的技术实现
• 用户想通过某个开源 Agent 项目学习 Agent 架构
• 用户想要一份能当参考手册用的 Agent 技术资料

不触发：

• 只问某个具体函数怎么实现（直接回答）
• 要求在仓库里改代码、修 bug、做 code review
• 只要一份几百字的项目简介

全书的六要素体例

每一章（收束章除外）都必须覆盖以下六个要素。缺任何一条，这一章就不成立——缺「原理」变成功能清单，缺「对比」变成项目广告，缺「权衡」变成教程抄写。

章节顺序可按内容需要调整（如把「对比」插在「原理」前后），但这六个要素不能少。

全书章节架构

六部分十四章。核心章必写，其余按项目实况取舍。

卷首（必写）

• 本书讲什么、适合谁读、怎么读（三条阅读路径：只想了解该项目 / 想学 Agent 架构 / 只想查某个机制）
• 案例项目概况：GitHub 地址、主语言、一句话定位
• 代码地图：只列本书会引用的 8–12 个文件及其职责，让人知道从哪读起。不是完整目录树

第一部分 认识这个系统

第二部分 运行时内核

第三部分 知识与记忆

第四部分 模型与协议

第五部分 规模化与工程化

第六部分 收束（必写）

附录（必写）：术语表、代码位置索引。

分级处理规则

事实来源标注规范

这是硬约束。用户会核对，编造一处就毁掉整份材料的可信度。

补充规则：

• 项目中不存在的东西，绝不写成本项目的实现
• 业界对比部分允许用 WebSearch 补充最新做法，但必须标注 【业界】，且不写具体版本号/发布日期
• 数字（阈值、轮数、token 上限）必须与代码一致；代码里是配置项而非硬编码的，写"默认 X，可配置"

写作流程

阶段一：读模板

读取 references/agent-book-template.md，获取各章的知识点清单、章内骨架样例、图表与代码呈现规范。

阶段二：把握案例项目

1. 读 README / docs / examples，判断项目类型与形态
2. 用「代码探索策略」中的锚点表定位核心文件
3. 建立代码地图：本书会引用的 8–12 个文件及职责
4. 形成架构假设清单：猜测的范式、主链路、机制分布 + 待验证疑点

阶段三：定章节目录

根据项目实况，对 14 章逐条判定：核心 / 有实现 / 无实现 / 删除。产出一份章节目录，标注每章预计篇幅与要写的知识点。

这一步必须显式完成。直接开写会导致章节失衡——前面几章写太细，后面草草收尾。

阶段四：落盘骨架

一次性写入文件骨架：卷首 + 全部章节标题与导读 + 附录标题，正文留占位。骨架先落盘，后续逐章填充，中途中断也不丢结构。

阶段五：逐章撰写

按章节顺序写，每章一次追加（用 Edit 替换该章的占位内容）。每章严格走六要素。

写每章前先问三个问题：

1. 这一章要让读者学会解决什么问题？
2. 业界的几种做法我能不能说清各自失效场景？
3. 本案例的选择在这个对比里处于什么位置？

阶段六：通篇校订

全书写完后回头检查：

• 术语是否全文一致（同一概念不要换三种说法）
• 章节间交叉引用是否正确（"见 4.3 节"这类）
• 有无重复讲述同一机制
• 有无【】占位符残留
• 有无章节失衡（某章明显比其他章单薄）

阶段七：交付

确认文件路径与文件名，报告篇幅与章节结构，说明哪些章因项目未涉及而作了简化处理。不执行上传。

代码探索策略

搜索锚点

探索纪律

• 大仓库用 Explore 子代理并行探索，围绕具体架构问题提问，不做无目的通读
• 精读范围限定：主链路 + 各机制核心文件
• 不读：前端界面、管理后台、部署脚本、测试用例、业务 CRUD 逻辑
• 读到的每个关键结论随手记下文件路径，避免写作时回查

深度要求

输出质量要求

• 教材感：每章读完要知道"为什么"，不能只留"是什么"。原理讲不透的章节，宁可压缩篇幅也不要堆砌。
• 对比意识：凡有多种做法的地方，必须给出对比表与各自失效场景。写"各有优劣"而不说清何时用哪个，视为不合格。
• 案例贯串：每章都要落到本案例上——选了哪种、在哪实现、参数多少。纯理论章节不超过 2 章。
• 诚实：严格按「事实来源标注规范」区分代码事实、业界知识、推断。
• 流程图：主链路每个环节、每个机制单元必须配图。图是理解架构的主要载体，读者多数时候先看图。
• 可查性：关键结论附 文件路径 → 函数名()，让读者能回到源码验证。
• 不注水：不写"综上所述""值得注意的是"这类填充句；不为凑篇幅重复已讲内容。

资源说明

references/agent-book-template.md

全书模板。包含：卷首格式、十四章逐章写作大纲（每章要讲哪些知识点）、章内骨架样例、图表与代码片段呈现规范、附录格式。

阶段一必须读取。阶段四落盘骨架、阶段五逐章撰写均以此为准。