问题记录与开发经验闭环

修订：issue-learning-2026-09-23-r1；owner：Codex；生效条件见规范登记。执行能力为 manual：依靠 Agent 读取、任务记录与审查；本轮没有增加自动检索、CI 阻断或模型训练。

入口与职责

入口	回答的问题	权威边界
问题台账	出现过什么问题，目前处理到哪一步？	索引和状态投影；事实、修复经过以链接的唯一问题主记录为准
问题主记录	为什么发生、考虑过哪些方案、改了什么、如何验证？	放 audit，或沿用已有任务/审计中的明确章节；使用问题模板
开发经验	遇到类似工作应先检查什么？	按机制提炼的注意事项；使用经验模板，不替代现行规范
CURRENT / FEATURE-MATRIX / gap-matrix	当前协调 / 能力 / 发布门禁	维持原职责；只有对应状态改变才更新

修复方案、任务、提交、验收报告通过链接串联，已有材料直接复用。一个 task 可处理多个 issue，一个 issue 可跨分析/实施任务；研究任务 done 不等于问题 resolved。一个 lesson 可覆盖多个同根因 issue。短问题可在任务主文档内记录，无需机械创建一套文件。

何时记录、检索和总结

设计、编码、排障或运维前：按模块、路径、错误码、症状和共用机制检索问题台账及经验索引。先查索引、再读命中条目的来源；核对当前源码/规范是否仍适用。在任务记录填写检索词、命中 ID、采纳的检查；无命中明确记录。简单信息答复不要求建任务或检索整库。
首次发现问题时：在当前任务 worktree 建立或补充问题主记录和台账行，记录预期/实际、影响、环境/版本、owner、下一步及证据缺口；尚未定位也可以登记。ID 使用 ISSUE-YYYYMMDD-<slug>，日期为登记日；发生日期另列，跨 worktree 以语义 slug 避免抢序号。
定位、改方案、完成修复或发现验收失败时：在同一主记录追加时间线和尝试结果；保留被否定假设、失败方案及不适用条件，区分观察、推测和已证实根因。按问题分析要求检查共用机制和同类入口。
根因与修复得到验证后、任务收口前：提炼经验或更新已有同机制经验，并链接回问题。若尚无验证证据，只能建 candidate；若没有新增可复用结论，记“不新增经验”及理由，仍保留问题记录。分析-only、未修复或验收失败的问题继续留在台账。
经验落到开发动作：写清触发条件、机制、应做检查、错误做法及原因、验证方法、适用边界。优先链接现有测试/约束；需要新增回归、lint、架构门禁或规范时，在当前授权内实施，超出授权则记录 owner/后续任务。仅提出自动化建议不能标为已落实。
复发或规则变化时：同一故障未解决的复现追加原 issue；已关闭问题再次出现，重开原 issue 为 investigating，递增 recurrence_count 并保留原关闭证据。不同根因建立新 issue 并互相链接。复盘为何已有经验/测试未生效：未检索、范围不适用、遗漏入口、检查未执行或实现回退，并更新防护。模块/接口/规范变化时复核命中经验；确认过时标 superseded 并链接替代条目，无替代则 retired，保留历史。

检索示例（在任务工作区执行，替换为本任务关键词）：

rg -n -i 'docgov|nullable|23503|职责' .doc/audit/ISSUES.md .doc/ops/lessons

owner 在上述里程碑及时更新，最迟在会话交接前保存事实和未完成项；不依赖定时服务。经验不会自动改变模型参数，作用是让后续 Agent 能检索、有证据地复用，并逐步把重复风险转换为可执行检查。

问题状态与关闭条件

问题的 issue_state 与任务 status 分开；台账保留当前投影，主记录保留变迁历史。

issue_state	含义 / 转移要求
open	已登记，等待定位
investigating	正在复现、验证假设和范围
fixing	修复方案明确且已获实施授权
verifying	修复待验收，或必要证据尚缺
resolved	约定范围的修复、必要环境验收均有证据，经验已总结或有不新增理由
deferred	暂缓处理；保留风险、责任人、复查触发和授权/决策依据，不冒充修复
duplicate	指向唯一主 issue，保留原报告和去重理由

定位失败可保留 investigating；临时止血不代表 resolved，必须标清剩余根治项。验证失败回到 investigating/fixing，不能覆盖失败记录。关闭至少能追溯：根因、同类范围、修复提交或获授权的处理动作、原例/变体/正常行为验收及缺项、实际部署状态、lesson 或不新增理由。业务改动待部署时不能把目标环境问题关闭；无需部署写 not_required。

历史补录：发生日、修复日和补录日分开。只按旧报告已证明的范围记录 resolved，同时标 evidence_basis=historical 和当前运行未复测；缺乏关闭证据用 verifying 并说明原因，不从旧任务 done 推导修复完成。历史条目不能用于宣布当前系统就绪。本轮仅补录两个有来源案例，不代表穷尽全部历史问题。

经验质量与维护

lesson_state：candidate | validated | superseded | retired。validated 表示注意事项有可核对的因果证据且已复核适用边界，不表示所有模块或当前线上均测试通过。需记录 reviewer、last_reviewed、reviewed_revision、来源 issue、证据日期、关键词、关联测试、适用/不适用范围及仍缺的防护。

同机制优先更新已有 lesson，保留修订记录；新机制才新增 LESSON-YYYYMMDD-<slug>。将通用经验升级成强制规范时，只在对应规范的唯一来源修改并登记生效条件，经验条目保留理由与链接。经验与现行规范冲突时先按有效规范执行，登记冲突与复核项；历史经验不能授予数据修复、部署或扩大范围的权限。

并发、验收与敏感信息

所有写入沿用 worktree 操作规范。问题/经验索引使用各自 path: 短租约；当前 agentctl docs apply 仅覆盖 CURRENT/FEATURE-MATRIX，不宣称新索引有行级 CAS。写入前读最新内容、只改自己的条目；从旧 dev 分出的工作区在集成前合并最新 dev 并处理索引冲突，保留他人条目。索引和主记录在同一逻辑提交同步，避免状态分叉。

文档验收包括链接/锚点、ID 唯一、主记录与索引状态一致、来源及日期、入口/模板可达和情景检查。运行回归按验证契约；未运行、缺项与历史证据单独标明。只保留足够判断的脱敏证据，业务正文、凭证和个人数据不复制进经验库。

7.1 KiB Raw Permalink Blame History Unescape Escape