状态
在仓库根目录维护 STATE.md：一份轻量级的跨会话日常报告，让下一个工作者只需阅读约15行即可了解项目当前所在位置、上一会话完成了什么、哪些即时经验值得复用、接下来该做什么，以及哪些未完成项不能被遗忘。这就是让开发经验不断累积而非每次会话都重新发现项目状态的反馈循环。
STATE.md 是临时性的（“我们现在在哪 / 接下来做什么”，每次会话都会重写）且自包含的——它不是存放持久决策、架构或术语表的地方，也不得重复这些内容。它是惰性创建的：如果文件不存在，第一次运行时创建。
如果项目持有计划权威（如问题追踪器、里程碑），则该权威负责做什么工作；它不规定执行的顺序和方式——问题可以并行处理，一个问题跨越多个会话，插入的工作可以抢占计划的工作。STATE.md 是工作者对执行的报告：结果，以及当前对跟踪工作的编排（下一步开始什么，中断了什么、暂停了什么）。它记录执行状态；绝不能成为第二个计划权威。
这个技能是自足且正交的，与项目可能使用的任何其他工具（版本控制、问题/任务追踪器、设计文档）无关。它假设这些工具可能存在，但不依赖任何特定工具——读取项目中已有的来源，跳过缺失的部分。
精简地写——宁可省略也不要误导。 模板中的每个内容项都是可选的。每当文件被重写时，更新日期是必需的。只有当内容准确且对下一个会话有用时才写入内容行。如果值缺失、过时、未经验证或不是明显有用，则省略。错误的或填充的线条比缺失的更糟。待办事项列表使用不同的删除规则；请遵循步骤4。
何时运行
- 在工作会话结束/收尾时——您的智能体运行时可能通过会话结束钩子提示此操作，或者您自己运行它。
- 按需调用，使用主机的显式技能语法调用
state技能。
主要工作者每个会话更新一次 STATE.md。并行子任务和子智能体不更新它。此规则防止并发或重复写入。
无操作保护： 如果会话没有完成实质工作（例如，简单的问答回合），保持 STATE.md 不变——最多刷新日期。不要用非进展来搅动文件。
工作流程
- 收集本次会话实际完成或更改了什么。 主要来源是当前对话。如果项目有辅助工具，则简要核实（最近的版本控制历史、问题/任务追踪器）——将其视为可选，非必需。
- 仅当您知道当前阶段时才陈述宏观阶段。 默认情况下不要将之前的 STATE.md 的阶段向前携带——如果它可能已经改变，或者您无法确认本次会话的当前阶段，省略该行，而不是断言一个过时的阶段。（把已完成的阶段写成当前阶段是误导。）使用项目自己的术语。
- 选择推荐的下一步工作——新会话应开始处理的未完成项，按执行顺序排列。当待办项是合适的下一步开始时，将其提升到此位置。
- 协调待办事项列表。 对未完成的跨会话项应用以下算法：
- 通过筛选继承。 从之前的待办事项列表和任何未运行的“下一步”项开始。仅在有证据表明某个项已完成、过时、已选定为“下一步”或已记录在项目追踪器中时删除它。追踪器引用是证据表明该项有了新家。检查对话并在有追踪器时与其核实。当状态不确定时保留该项。
- 降级未完成的工作。 仅当未完成的工作未被选定为“下一步”时，才将其移至待办事项列表。应在下次会话继续的工作属于“下一步”。
- 搁置延迟的工作。 当新接受的项被推迟到下次会话之后且没有其他归宿时，添加它。
- 给每个项一个家。 将其放在“下一步”或待办事项列表中，绝不能同时放在两者中。
- 给每个待办项打上时间戳。 记录其进入日期为
since YYYY-MM-DD。 - 应用五项预算。 当待办事项列表超过五项，或某个项明显重要时，将项按从旧到新的顺序移至项目的追踪器。仅在追踪器提供引用后删除项。如果没有追踪器，则保留所有项。当没有授权编写者可以创建追踪器记录时，也要保留所有项。可见的溢出是信号表明这些项仍然需要一个持久的家。
- 仅在经验有助于“下一步”时添加。 仅当本次会话的工作与推荐的下一步工作连续或相关时才包含笔记，这样笔记才能实际被复用。如果下一步工作无关，省略它——不帮助下一个任务的经验只是噪音，而不是战争故事存档。当项目有
PITFALLS.md时，将持久的环境、工具、权限、沙箱和工具调用指导放在那里。STATE.md 可以指向相关条目；不应复制该条目。 - 从模板重写
STATE.md。 覆盖文件；绝不追加。保持其不超过15行。如果步骤4中的无损失规则导致超过五个待办项，允许每多一个项额外增加一行。不要为了满足行数限制而删除项。省略不准确或没用的内容项。将筛选后的待办事项列表作为新快照的一部分重新输出。打上更新日期。 - 不要自动提交。 只需将重写的
STATE.md留在工作树中。它是否被跟踪或作为仅本地的工作辅助工具是由项目决定的——此技能从不提交它。
模板
# 状态 — <项目>
_跨会话日常报告（约15行，每次会话通过 `state` 技能重写）。持久决策存放在别处，不在此处。_
- **阶段/里程碑：** <当前阶段，使用项目自己的术语——如果您无法确认*当前*阶段则省略>
- **上一会话：** <已完成/更改的内容；一行，例如 issue #N>
- **经验：** <有助于“下一步”的瞬时经验，或指向相关 `PITFALLS.md` 条目的链接；否则省略>
- **下一步：** <推荐**开始**的项，按执行顺序，例如 issue #N>
- **待办事项：** <未完成的跨会话延续项，**未**选定为“下一步”；每项一行>
- <中断或暂停的项，如果有追踪器引用则锚定它（#N）> _(since YYYY-MM-DD)_
- <尚未在追踪器中的项——列表溢出时按从旧到新将其提升到追踪器> _(since YYYY-MM-DD)_
_更新日期：<YYYY-MM-DD>_
（每个内容项都是可选的。_Update 每当文件被重写时必须存在。）
护栏
- 对待办事项列表的每次更改都遵循步骤4。切勿通过删除未完成的工作来满足预算。
- 遵循步骤6进行重写和行数限制。STATE.md 是当前快照，不是历史日志。
- 仅记录本次会话的增量。待办事项列表是唯一向前携带筛选后状态的字段。
- 保持文件自包含。不要重复持久决策或依赖于特定的追踪器或工具。
- 使用项目已建立的词汇。