跳到正文
擎天文档返回官网 ↗
文档/方法参考

大型交付的工作记录与持续日志

本页内容

仅在大型交付中使用。本参考拥有记录载体、模板、读写和恢复方法,不决定任务 flow、验收标准或整体完成。验收正文由验收合同方法维护,设计由原 Design owner 维护。

固定入口与职责#

默认布局如下;已有项目等价载体映射一次,写入工作记录,不另建同义副本。一个大型交付保持一个稳定恢复入口,不因跨轮或多批日志复制当前进度。

docs/designs/YYYY-MM-DD-<topic>.design.md
docs/work/YYYY-MM-DD-<delivery-slug>/
  acceptance-contract.md
  delivery-goals.md                      # 交付目标清单与逐目标验收详情
  current-state.md
  artifacts/                             # 按需:附件不自动构成验收证据
docs/logs/YYYY-MM-DD-<topic>/
  README.md                              # 含“原始输入与约束”章节或独立文件入口
  YYYY-MM-DD-inputs.md                    # 按需:原始输入与约束较多时独立承载
  records/YYYY-MM-DD-<topic>.md           # 按需:过长或需独立审查的过程详情

日期是记录创建日;同一委托跨天沿用目录,同日独立委托用可区分的主题。work 使用单数。日志也支持 v<semver>-<slug>/README.md,新建默认日期,旧记录原地续写,不为同批造日期/版本双副本。目录身份与实际发布版本分开,项目专属章节可保留。

日志保存原始输入与约束的来源记录、关键历史与交付汇总;合同引用来源,保存当前有效约定与验收账本;design 保存方案、对齐依据和理由;delivery-goals 保存规划功能/可执行任务及其验收状态;current-state 保存当前推进任务、实际动作、整体现场与恢复导航。plan 遵循原触发门,只承载必要安排,不平行维护任务状态;附件和长详情按需,不要求每工作项另建文件或机械填表。

旧任务的 working-notes 或项目等价入口原地续写,不并建第二份。明确改名时同步所有当前入链,保留历史可定位性;两种名称并存不能仅凭新名称或修改时间判定权威,应沿任务入口与实际内容消歧。

交付目标清单#

大型交付在同目录维护 delivery-goals.md。它是按规划功能和可执行任务拆分的交付清单,不因文件名而强制写成“用户能做什么”的上层效果。 上方表格列任务、优先级、状态、完成标准和证据/差距,下方用稳定ID记录每项详情。命名直接说明本次做什么,例如“消息回执与异常恢复”“场景A集成验收”;用户效果体现在对应验收标准里。

粒度以可执行、可验收的完整部分为准:可列规划功能、独立开发任务、必要调查/设计交付、集成验证或适用发布。安装一条依赖、临时排错、改一个变量等操作通常留在current-state/日志,不强制逐项穷举;若某项迁移/调查本身有独立交付和验收边界,则可以成项。不要只留下宽泛愿景,也不要按文件数、命令数或会话机械拆任务。无实际理由不新增旧入口兼容,当前引用直接迁移。

# 交付目标清单
## 整体范围与入口
- 本次规划范围、合同/设计、当前执行记录
## 任务总览
| ID | 功能/任务 | 优先级 | 状态 | 完成标准/验收引用 | 证据或剩余 |
| --- | --- | --- | --- | --- | --- |
| T-01 | 消息回执与异常恢复 | P0 | 待补齐 | AC-01、场景A相关用例 | 现有服务端确认;缺端侧回执 |
## T-01 · 消息回执与异常恢复
- 任务目标:本项具体实现/验证什么
- 功能范围及边界;必要设计/依赖入口
- 完成标准与验证方法,引用已有合同的具体用例/ID
- 已有实现和证据、剩余工作或阻塞

状态和优先级只在总表维护,详情不重复动态状态。可使用待开始、待补齐、进行中、待验收、受阻、已完成等明确状态;实际开展才标进行中,实现好但证据未齐仍待验收。无负责人、计划日期或过程操作数量的强制字段;详情是结构化信息,不要求折叠UI或每任务一份文件。

  1. 执行与变更:从未完成任务选择当前最能推进完整链路的工作。新发现若补齐规划范围内必要的独立功能/任务,新增稳定ID及来源、范围、完成标准;原任务内的实现细节或缺陷则更新其剩余/执行记录。实现方法可以改变,不能借调整任务名降低用户标准、删除Required或将必需任务转候选。
  2. 逐项验收:完成须有与本项范围相符的实现/产物、有效验证/适用Review及本项交付证据;旧局部通过、已写代码或步骤执行完都不自动算完成。子任务没有独立发布要求时以进入约定集成位置为准,不强制每项发布。
  3. 场景与收口:整体代表场景和适用发布可独立成项,具备条件就试跑,失败回原任务。最终版本变化只使受影响证据失效,重开对应任务。全部当前必需任务完成只是必要条件,仍须反查parent-goal、Required场景及授权内交付有无遗漏,由Lifecycle判断整体完成;候选增强不混入当前承诺的统计。
  4. 跨会话接续:current-state链接清单,记录当前任务ID、现场和整体下一步;日志留来源、尝试、失败和决策。恢复先读总表、当前任务详情及相关合同/设计/证据,再接续实际工作,不从最近提交或局部成功猜整体完成。文档不自动授权跨会话消息、子代理或后台运行。

合同拥有有效标准和细粒度用例结果,任务表引用它们,不复制另一份用例判定。只有任务进展、证据或剩余变化时更新对应行/详情;不每操作一次就重写全部文档。文件名和任务表述方式不能成为限制合理拆分、强造抽象目标或新增管理层的理由。

原始输入与约束#

在依赖这些输入设计/实现前整理到本任务 docs/logs/。默认用 README 的同名章节;多份原型、长要求或需要独立引用时拆为 YYYY-MM-DD-inputs.md,README 保留入口。同一任务只维护一处,不每日复制;已有等价原始材料可直接链接,在日志中保留索引与用途说明。

按实际输入保留以下内容,短内容可用列表,不强制表格:

  • 来源与版本:用户表达的日期及必要原话,HTML/图片/附件/文档的可访问位置,commit、内容校验值或明确版本;可变且不可回溯的来源按权限保存必要快照,不假称未提交内容已被 Git 保存。
  • 预期与用途:用户希望得到的结果、必须保持的功能形态/交互/外观或其它约束;明确材料是实现基准、部分参考还是待探索。区分用户明确要求、确认选择、授权内决定和 AI 推断;角色不明且影响结果时才澄清,不把全部素材细节自动变成硬约束。
  • 范围与未决项:哪些部分适用、明确排除什么、缺失/冲突/尚未确认的内容;关联当前合同条目,已有 ID 则引用,不为每句原话新建编号。
  • 后续补充与替代:保留旧来源,追加纠偏或替代关系及生效依据;当前有效标准仍由合同决定,日志不另维护一份现行验收表。

先读相关原件再提炼,摘要只作导航。合同、设计和当前状态都能定位该记录;新输入须在后续依赖动作前更新。未提供原件时如实记录,不虚构已核对。敏感材料遵守项目权限,不复制凭据或受限数据。

当前状态模板#

# 当前执行状态
## 身份与入口
- 交付主题;整体状态(进行中/暂停/阻塞/待验收/已完成/已停止);最近核对时间
- contract-id;合同路径与修订;原始输入记录;整体/当前部分设计的具体段落及 Review 指针;日志;plan(有则链接)
## 执行现场
- 仓库/工作区、分支/产物;本任务未提交改动的定位及与其它 WIP 的边界
- 接续所需的运行环境、操作标识和核验入口(适用才填,不存凭据)
## 当前进度
- 当前环节、当前任务ID及delivery-goals入口;相关验收ID与证据指针,不复制全表状态
## 未闭合事项
- 待设计部分与触发点;失败/过期验证、未关闭 findings;待决定/外部条件
- 未核实动作;待同步文件及修订(无则写无);引用原记录,不复制历史
## 下一步
- 下一具体动作及前提

工作记录从已有任务/设计入口可达;交接或压缩摘要保留其路径。有效标准和验收状态以合同原账本为准,任务状态以delivery-goals为准;当前状态只链接它们并选取下一项,不复制第二份。整体执行状态不代替验收结论,不因普通进展提升标准修订号。已完成时回链实际交付,未完成项不能借整理移出范围。

查找与接续#

仅在用户要求恢复/继续或当前任务需要接续时查找,不因打开项目自动执行旧任务。优先使用用户、任务、设计给出的入口;没有入口时列出本项目 docs/work/ 下 current-state.md 和旧 working-notes.md,先读候选的身份与状态。其它布局沿项目路由/日志的明确映射找回,不全量加载历史。

按本次用户意图匹配交付;多个未完成项不能按日期新旧选,也不能全部启动,无法消歧才询问。缺状态字段视为未知;已完成/已停止记录不是默认续做目标。暂停或停止任务须有明确恢复指令;模糊“继续”不解除其它任务的暂停。

选定后读有效合同、适用设计和必要证据,再核对实际工作区与未核实外部动作。先前记录的状态不等于当前事实;找不到产物、发现版本变化或指针冲突,先修复相关恢复信息,不盲目重做提交/部署。依赖缺口的动作暂停,其它独立工作沿原授权继续。

日志模板与及时记录#

大型交付在首次需要保存输入时就创建或复用日志,最迟执行启动时建立;不用等全部完成。纯讨论继续原讨论/设计,不借此启动实现。默认 README 模块为:关联入口 → 原始输入与约束(或其链接) → 过程记录 → 交付汇总与复盘;项目已有交付章节映射承载,不再复制汇总。

  • 关联入口:contract-id、原始输入章节/文件、合同/设计、唯一工作记录。
  • 过程记录:按时间或可靠顺序追加“主题 → 实际观察/决定/失败 → 依据链接 → 对后续的影响”。待验证/未完成如实写明。
  • 交付汇总与复盘:进行中注明尚未交付;收尾汇总实际范围、可用入口、验证与 Review、重要修订、限制及经验落点,引用原过程。

预期或关键方案改变、实验/验证结果、重要集成节点、失败/排除路径/返工、Review finding、外部操作与阻塞变化,均须在后续依赖动作前及时落盘。同一短工作单元可合并细节,不逐命令记账。关键实验先保存问题与判定;普通实现引用已有标准。外部动作先留意图与核验入口,完成后记录真实结果。

较长详情妨碍浏览或确需独立 Review 时才拆 records/YYYY-MM-DD-<topic>.md,模块为“问题与判定、过程与依据、结论与影响”,README 留摘要/链接。日志不逐执行命令编号;任务保留delivery-goals中的稳定ID,过程不强制逐项登记。返工更新原主题并保留失败及纠正依据。附件放 artifacts 或引用已有稳定来源,不存凭据或复制受限原始数据。

更新与恢复#

普通关键进展写日志;任务进展、证据或剩余变化时更新delivery-goals对应行/详情,执行动作与整体现场变化更新current-state;验收新证据更新合同原账本;新约定生效才修订合同/设计并使受影响证据 stale。不每次重写全套文件,也不重验无关风险。

证据/Review 记录注明适用约定、产物版本或实际工作区差异、环境、结果与限制及可恢复定位;未提交改动不能只绑定不含改动的 HEAD。finding 关闭依据留在原记录,后续总结不能掩盖未关闭问题。短结论可直接保存,长输出引用附件。

多文件变更先在笔记留下待同步对象,修改权威 owner,再对账受影响引用与证据,完成后清除待同步。不是原子事务:中断后先检查版本、工作区和未知结果的外部动作。旧约定无可访问历史时保存必要差异或只读快照;不得假称 Git 已保存未提交内容。

结束轮次、等待或交接前刷新当前状态,但不能只等可预测的压缩通知才保存。恢复依次读当前笔记、有效约定、相关设计和必要日志;不全量重读历史,不把摘要当合同。缺失会影响决策的材料先恢复或澄清,其它独立工作继续。

日志保留当时事实,当前下一步只有工作记录一个 owner。状态使用显式字段(如 - 整体状态:进行中,也支持身份行中分号分隔的 状态:已完成);下一步可用 - 下一步:具体动作 或上述同名标题下的正文。示例代码和 HTML 注释不作为大盘当前状态。后续纠正关联原事件;补录注明来源与未知。完成后原材料和引用保留,不能靠回忆补全过程;下一独立任务不覆盖旧记录。