从 Context Engineering 到可执行的研发工作流:让 Agent 在持续累积的项目上下文里工作,把需求写成文档,把验收交回给人。
llmdoc:一套文档驱动的项目上下文系统,让 Agent 从"每次重新理解项目"变成"基于持续累积的上下文工作"。
先 DeepResearch 调研,再让 Coding Agent 把需求写成 vision / plan / loop / Dod 文档;实现全程 Agent 自检、文档随变更更新, 最后人工验收。
Folo cli + Marvis 自动任务:把资讯获取从"主动刷"变成"自动送到"。
llmdoc —— 面向 Claude Code 与 Codex CLI 的文档指引 AI 编码工作流,把上下文当作可维护的工程资产来治理。
每个工具的名称、描述与参数 schema——存在即占上下文。
system prompt、CLAUDE.md / AGENTS.md、skill 与 hook 注入的指令——定义 Agent 怎么做事。
memory 文件、llmdoc 等跨会话内容——唯一能被工程化治理的一层。
工作目录、git 状态、平台、日期等自动注入的运行时事实。
用户指令与助手回复的全部记录,随多轮任务持续累积。
Read / Grep / Bash 的输出,通常是上下文消耗的最大来源。
同一块上下文窗口,六类内容在竞争——Context Engineering 就是管理这场竞争。
llmdoc 让 AI Agent 从“每次重新理解项目”,变成“基于持续累积的项目上下文工作”。
在真实工程项目中,LLM Agent 的瓶颈不是能力不足,
而是上下文组织方式不稳定。
重新搜索入口、重新理解模块关系、重新判断约束,大量重复的 Glob / Grep / Read 消耗首轮上下文窗口。
架构边界、设计意图、历史决策散落在代码、注释、PR 与对话中;只靠临时搜索,容易只看到局部实现。
一次任务中发现的经验如果不沉淀,下一次对话就会丢失——相同的调研与错误反复出现。
全量塞给模型会污染上下文窗口;完全依赖人工维护,文档又容易过期。两者之间缺一个可执行的更新流程。
Claude Code 与 Codex CLI 的插件、skill、subagent、hook 机制不同,方法论需要收敛到共享文档再分别适配。
启动只读最小必要上下文,任务深入时按路由规则分层读取——从全量注入变为按需加载。
文档不是源码摘要,而是导航层;源码仍是最终事实来源。
.llmdoc-tmp/ 存临时调查结果, llmdoc/ 存稳定知识,互不污染。
不同生命周期的信息有不同 owner,避免临时判断污染长期文档。
以 watermark-commit 为基准检测变更,按范围与风险选择最轻的更新模式。
llmdoc/index.mdllmdoc/startup.mdllmdoc/must/ 短规则overview/ 项目身份、边界、主要区域architecture/ 架构流程、不变量、所有权guides/ 可重复执行的工作流reference/ 稳定事实、路径映射、接口约定memory/ 反思、决策、已知文档缺口核心转变:上下文读取从全量注入变成按需加载。
这个项目是什么?
哪些文件定义了公开接口?
某个工作流应该读哪些文档?
哪些设计约束不能破坏?
哪些结论已被验证、值得长期保留?
源码仍是最终事实来源;llmdoc 负责帮 Agent 更快找到正确源码,并理解其背后的稳定意图。
分层的意义:临时判断永远不直接写入长期文档。
证据驱动的调研,回答"现状是什么",不下长期结论。
执行明确的代码或文档任务,遵循 must 规则与路由文档。
维护稳定 llmdoc/ 文档、索引与同步状态,直接读原始调研结果。
记录任务后的过程反思,捕捉容易复发的过程信号。
重点不是"更多 Agent",而是让不同生命周期的信息有不同的 owner。
自有提交、影响文档明确——直接更新受影响文档。
含他人提交,或需要一次聚焦的 investigator 调研后再更新。
多批回填、独立反思——investigator + reflector + recorder 完整编排。
原则:永远选择最轻的、足够的更新模式。
自然语言任务
共享方法论,分别适配入口
日常任务入口
初始化编排
更新编排
一次任务只走树的一条分支——入口决定编排,编排决定读哪些文档、动用哪些角色。
进入项目即获得加载规则
index.md → startup.md → must/
需要更多上下文时按路由读文档,必要时读源码验证事实
在稳定意图的约束下工作
是 → 考虑运行 /llmdoc:update,同步回稳定文档
每一次任务结束,都可能让下一次任务的起点更高。
创建 llmdoc 目录骨架
第一轮 investigator 覆盖主要仓库表面
有缺口 / 冲突 / 未解关系 → 补充调研 pass
直接读原始调研结果,生成 must / overview / architecture / reference
完成初始化
非平凡仓库不依赖单个广泛调查——按主题并行调研,避免第一轮盲区进入稳定文档。
recorder 直接读取原始调查结果,而不是只读二手总结。
计算 watermark..HEAD 净变更,合并工作区未提交变更
按范围 / 作者 / 风险 → fast · analysis · full
analysis / full 启动 investigator;有流程教训时 reflector 写 reflection
同步 index.md,清理或更新 doc-gaps.md
可安全推进 → 更新 sync.md;否则保留 watermark
变更检测基于 commit watermark,而不是日期或主观记忆;未提交变更参与更新,但不推进 watermark。
文档只记录稳定结论,不归档所有任务细节;.llmdoc-tmp/ 是证据缓存,不是稳定记忆。
它关注的不是单条 prompt 怎么写,而是工程项目中的上下文如何被选择、组织、压缩、读取、更新和治理。
startup.md、must/、index.md 控制启动时读什么;高频稳定信息进启动上下文,低频专项按需读取。
把架构意图、模块边界、工作流规则压缩成短文档,Agent 不必每次从源码重新推断。
index.md 与 reference/repo-surfaces.md 充当路由表,把"我要改什么"映射到"应该读什么"。
reflections/、decisions/、doc-gaps.md 让项目经验跨会话累积——保存容易复发的过程信号。
/llmdoc:update 让记忆跟随代码演进;commit watermark 保证更新有明确基准。
临时证据、过程记忆、稳定知识、机器状态四层分离,降低上下文污染。
memory 记住"你是谁、怎么工作";llmdoc 记住"这个项目是什么、该怎么动它"——互补,不互相替代。
开始任务时,读取最小但高价值的上下文
需要深入时,按概念路由到相关文档和源码
完成任务后,把值得复用的经验同步回稳定文档
下一次任务,再从这些稳定文档中受益
有了稳定的项目上下文,下一步是把它用进日常开发工作流。
先调研、再写清需求、然后让 Agent 实现——vision.md · plan.md · loop.md · Dod.md,最后人工冒烟验收。
先做深度调研,产出调研报告——不带着空白脑子开工
带着调研报告和 Agent 聊,把需求、边界、约束聊清楚
vision.md · plan.md · loop.md(可选)· Dod.md
playwright · chrome-devtools-mcp 等,Agent 边实现边自验证
实现全程持续自检;出现影响 Plan 走向的变更 → 先回写 plan.md / Dod.md 再继续
Agent 自验证之后,人对核心路径做最终验收
核心思想:需求先被写清楚,代码才被写对;文档随实现持续更新,不是一次性产物。
做什么、为什么、不做什么——对齐目标的单一事实来源。
任务拆解、执行顺序、依赖关系,让实现过程可分步检验。
需要多轮循环时的节奏、检查点与退出条件。
Definition of Done:可逐条检验的验收标准清单。
文档是人和 Agent 的共同契约——先评审文档,再放行代码;实现中变更影响走向时,plan / Dod 同步更新,而不是事后补写。
playwright 浏览器自动化:Agent 能真实打开页面、点击、截图chrome-devtools-mcp 查看 console、网络请求、性能,自己排查问题Dod.md 逐条过核心路径工具让 Agent 能自我证证, 回归测试让人保证最终验收标准。
Folo cli + Marvis 自动任务:资讯获取从"主动刷"变成"自动送到"。