寻路

一个松散的想法来了,大到单个会话装不下,裹在雾里:从这里到目的地的路还看不见。寻路是找这条路,不是冲向目的地。本 skill 把路绘成 .agentdocs/workflow/ 下的共享地图,然后逐张解决它的决策工单(问题是决策的工单,不是待执行的活),直到路线清晰。

目的地因工程而异,命名它是绘图的第一步:它塑造每张工单。可能是一份交给 task-spec 的规格,一个开工前要锁死的决策,或一处就地完成的变更(数据结构迁移)。地图与领域无关:工程工作、内容创作,合形状即可。

合格的目的地一句话说清到达终点的样子,而非要做的事:

• 规格型:"一份定稿的规格,让 /task-tickets 能直接拆出执行工单";
• 决策型:"选好消息总线是自建还是托管,并锁死选择理由";
• 变更型:"用户表从单表拆为分表,数据迁移完成,线上读写已切换"。

判据是可核对:走到终点时,agent 能分辨到了没到。"想清楚架构"不合格——它是要做的事,且永远可以再想清楚一点。目的地定死范围:它之外的工作是范围外,不进这张地图。

规划,不动手

寻路默认是规划:每张工单解决一个决策,地图完成 = 路已清晰、动手前没有要决定的了。想直接动手的冲动,通常正是你摸到地图边缘、该移交的信号。工程可在地图的 Notes 里覆盖此默认,把执行也带进地图;没有覆盖,就产决策,不产交付物。

以名称指代

人读到的一切(叙述、地图的"已定决策")用地图与工单的标题指代它们,不裸用编号或文件名。一墙 #42、#43、#44 无法阅读;名称一眼可读。编号不消失:链接里的路径带着它,但它骑在名称里,从不替代名称。

地图

地图是任务目录下的单个文件,该目录即本工程的唯一事实源:

.agentdocs/workflow/<YYMMDD>-<map-slug>/
├── map.md            # 地图:低分辨率全景,每会话加载一次
└── tickets/
    ├── 01-<slug>.md  # 决策工单:每张一个文件
    └── ...

建立时在 .agentdocs/index.md 的"当前任务文档"追加条目。

地图是索引,不是仓库:列出已做的决策、指向承载细节的工单;一个决策只活在一个地方——它的工单;地图只留一行主旨与链接。

地图正文

# <地图标题>

## 目的地

<到达终点的样子:要产出的规格、要锁死的决策、要完成的变更。一两行;每个会话选工单前先对着它定位>

## Notes

<领域;每个会话都该查阅的 skills;本工程的长期偏好>

## 已定决策

<!-- 索引:每张已结工单一行,足以判断相关性,细节看链接 -->

- [<已结工单标题>](tickets/<NN>-<slug>.md): <答案的一行主旨>

## 尚未具体化

<!-- 雾区:范围内还无法开票的问题;随前沿推进逐渐毕业 -->

## 范围外

<!-- 被排除在目的地之外的工作;已关闭,永不毕业 -->

工单

每张工单是 tickets/ 下一个文件,标题即其名称。正文是问题,量级适配一个 10 万 token 的会话:

# <NN>: <工单标题>

## 问题

<这张工单解决的决策或调查>

**类型:** research | prototype | interview | task
**阻塞于:** <NN-工单标题> 或"无"
**状态:** ready | in-progress | done

答案不写在正文里:解决时追加 ## 答案 小节并关状态。解决过程中产生的资产(原型、调研笔记)以路径链接,不粘贴。

阻塞边决定前沿:开放、无阻塞、未认领的工单集合,已知的边缘。

工单类型

每张工单要么 HITL(人在环,与人一起解决,人为自己发声),要么 AFK(agent 独自驱动)。HITL 工单只能通过现场交流解决;agent 绝不替人站岗(interview 自己的问题的访谈已经坏了规矩)。

• research(AFK):读文档、第三方 API、本地知识库,浮出一个决策在等的事实。由调 Skill 工具执行 research 的子代理解决。当前目录之外的知识需要时用;
• prototype(HITL):造一个便宜、粗糙、具体的可反应之物(提纲、草稿、桩、UI/逻辑代码)抬高讨论保真度,调 Skill 工具执行 prototype。原型作为资产链接。"该长什么样 / 该怎么表现"是关键问题时用;
• interview(HITL):对话,默认类型。调 Skill 工具执行 interview(它内联沉淀术语与决策);
• task(HITL 或 AFK):决策之前必须发生的动手活:无可决策、无原型可做、无资料可查,但讨论被卡到它完成。注册服务以便评判其 API、开通权限、搬数据看清形状。唯一做而非决定的类型,资格是解锁一个决策,不是交付目的地。agent 能独自驱动就 AFK,否则给人一份精确清单(HITL)。完成即解决;答案记录做了什么与后续工单依赖的事实(凭据位置、新 URL、行数)。

雾区

地图刻意不全:看不清的不绘。活工单之外是雾区:你能预见、还无法钉死的问题——它们悬在仍未决的问题上。解决一张工单清开它前面的雾,把现在能具体化的毕业成新工单,一次一张,直到通往目的地的路清晰、工单清空。

地图的"尚未具体化"写暗视图:疑似的问题、日后要重访的区域。它是朝向目的地的未知边缘:一切都在范围内,只是还不够锐利到开票。**雾还是票?**判据是现在能否把问题说精确,不是现在能否答上:问题已锐利(哪怕被阻塞)→ 开票;还说不锐 → 入雾。不把雾预切成工单大小:雾比工单粗,一块雾到前沿时可能毕业成几张票,也可能一张都不是。

"尚未具体化"排除已定的(已定决策)、已是活票的、范围外的(下一节)。

范围外

雾只朝目的地聚拢。目的地固定范围,其外的工作是范围外:它不是雾,不进"尚未具体化",在地图上自成一节:你有意排除在本工程外的工作。范围外的工作永不毕业(前沿止于目的地),只有目的地重绘时才回来,且作为新工程,不是续作。

把一件事划出范围是圈定动作,不是路线上的一步。已有的工单事后发现越界(绘图中误圈、或被某张答案暴露)时:关闭它(关状态的工单明确不在前沿),在"范围外"留一行主旨与理由,链接该工单。它不进"已定决策"——那里记录实际走过的路线;范围边界不是路线上的一步。

调用

两种模式。无论哪种,每会话至多解决一张工单,research 型除外。

绘制地图

用户带着松散想法调用:

1. **命名目的地。**调 Skill 工具执行 interview,钉死这张地图要寻到什么:规格、决策、变更。目的地固定范围,先定它;
2. 绘制前沿。再次访谈,这回广度优先:横向扫过整个空间,而非深钻一线,浮出开放决策与现在就能做的第一步。若没有扫出雾(路已清晰、整个旅程一个会话装得下),不需要地图:停下问用户想怎么继续;
3. 建地图:目录、map.md(目的地与 Notes 填好,已定决策为空,雾写入"尚未具体化"),index.md 追加条目;
4. 开现在能开票的:写入 tickets/,第二遍连阻塞边(先有编号才能互相引用)。连边后分出前沿与被阻塞的;开不了的留在雾区;
5. 发射 research 子代理:刚建的每张 research 工单,并行派调 Skill 工具执行 research 的子代理解决,发现写入任务目录 research/ 子目录,工单留指针;
6. 停:绘图是一个会话的活,不亲手解决任何票。

走地图

用户带地图(路径)调用,可带一张工单:

1. 加载地图:低分辨率视图,不是每张工单正文;
2. 选工单。用户点名就用它;否则按序取第一张前沿工单;
3. 解决它。按类型调对应 Skill 工具;吃不准就调 Skill 工具执行 interview。需要时取相关或已结工单的全文;
4. 记录解决:工单追加 ## 答案 小节、状态改 done,地图"已定决策"追加一行主旨;
5. 补新浮出的工单(先开票再连边);答案让哪块雾变得可具体化,就让它毕业成票,并从"尚未具体化"清掉。答案暴露某张票越界时,按"范围外"处理;答案动摇地图其他部分时,更新或删除那些票。

全部工单结清、雾散尽时,地图完成:移交主流程——把已定决策交给 /task-spec 定稿为规格,再 /task-tickets 拆执行。旅程意外地小就直奔执行,但默认走规格,丢掉链接里的细节才是浪费。