项目上下文
目的
将持久的仓库上下文保存在普通文件中,以便后续会话无需重建状态即可恢复。
使用 / 不使用
当仓库工作需要跨线程或跨代理的持久上下文时使用此技能:恢复或交接、长时间运行的工作、子代理跟进、可复用的参考笔记、当前任务摘要或仅追加的日志。
不要为只读问题、一次性检查或隐式迁移分散的旧文档进行初始化。如果布局缺失,请选择显式采用或迁移。
核心倾向
- 优先使用普通仓库文件,而非外部系统或隐藏内存。
- 当前可信主题上下文:
docs/reference/**。 - 当前任务恢复状态:
BRIEF.md。 - 仅追加的跟踪记录:
logs/*.md。 - 小规模契约、可移植路径、不含机密。
- 当复用不明确时,创建新的带日期任务。
契约
docs/
reference/**/*.md
tasks/yyyy/mm-dd/<task-slug>/
BRIEF.md
logs/{DECISIONS,WORKLOG}.md
[可选] <目的命名的待办事项>.md
[可选] working/
[可选] archive/
[可选] BACKLOG.md
docs/reference/**:仅当前可信参考上下文。在此处保留可复用的规则和可靠事实,而不是调查历史、进度、时间线叙述、代码索引、实现导览或源文件目录。仅包含验证规则或事实所需的最小所有者接口路径。当用户更正或删除请求影响参考声明时,重写或移除过时的声明;仅保留已更正的可靠事实或指向权威所有者的指针。docs/tasks/yyyy/mm-dd/<task-slug>/:实际工作的默认任务工作空间。BRIEF.md:仅重写的紧凑恢复卡片,不是报告或日志。保持稳定的目标、范围边界、当前事实或结论、当前可恢复状态以及最近的下一步。- 在长时间运行的工作中,在每个阶段边界重写
BRIEF.md,使其仅包含当前可恢复状态;将阶段历史和证据移至logs/、working/或archive/。 logs/DECISIONS.md和logs/WORKLOG.md:仅追加的决策和执行跟踪记录。将证据保留在此处,而不是在摘要中。[可选] <目的命名的待办事项>.md:仅未解决的遗留事项,例如RESEARCH-BACKLOG.md或QA-BACKLOG.md。仅当一个下一步不够时添加。[可选] working/:进行中的草稿、探测、暂存证据和未决定的计划。[可选] archive/:已完成、已拒绝、已替换或过时的遗留记录,不再拥有当前状态。[可选] docs/BACKLOG.md:仅尚未激活的仓库级别未来工作。一旦激活,将状态移入一个带日期的任务并移除仓库待办事项。
BRIEF.md 所有权
除非用户明确要求,否则仅使用以下顶级标题:
目标或意图范围当前理解或当前事实当前状态下一步或后续行动- 可选
工作边界
语义规则:
-
通过重写当前状态应用用户更正和删除请求;
BRIEF.md仅保留结果事实、边界或下一步。 -
目标仅陈述稳定的任务目标。将背景和理由保留在其他地方。 -
范围是边界摘要,而非已接触文件列表。 -
当前理解仅用于紧凑的结论。当可复用时,将设计策略或持久结论移至当前规范的 task doc 或docs/reference/**;将调查笔记、基准表和暂存证据移至working/或日志。 -
当前状态说明如果任务现在恢复,什么为真。将“已完成事项”的叙述移至logs/WORKLOG.md。 -
下一步仅包含最近的可重新启动步骤,而非待办事项。对于已完成的工作,在有用时使用紧凑的如果...则重新打开条件。 -
不要添加诸如
验证、已更改文件、已接触文件、历史、工作日志、调查、证据、已完成或检查清单等章节。 -
不要包含命令输出、验证记录、调查历史、基准矩阵、PR/发布/部署时间线、已完成工作历史或已接触文件清单。
-
如果验证状态重要,在
当前状态中用一句话总结,并将细节保留在logs/WORKLOG.md中。 -
如果精确路径能显著降低重新打开的成本,将最小的有用仓库相对路径集放入
工作边界,通常最多 5 个路径。 -
预算为软性审查触发器:通常保持
BRIEF.md在 300-500 字左右,每个部分大约 1-5 个要点,范围大约 1-3 个要点。反复的压力意味着材料需要另一个所有权接口。
任务根目录所有权
- 任务根目录仅拥有当前规范的文档和路由。每个根目录标记文件应回答“这是此主题的当前来源”或“这将读者路由到当前所有者”。
- 小型任务默认为
BRIEF.md、logs/DECISIONS.md和logs/WORKLOG.md;较大任务可在它们使任务更易于扫描时添加当前规范的文档或路由。 - 将活动的草稿、探测、暂存证据和未决定的计划放入
working/;将时间线和验证细节放入日志;将已完成、已替换或过时的文档放入archive/。
日志限制
日志是仅追加的,但不是命令记录。
对于 logs/WORKLOG.md:
- 每个有意义的工作批次追加一个块,而不是每个命令或文件。
- 将重复的编辑、重试、验证尝试和反馈微迭代合并为一个简短的结果块,在集群稳定后添加。
- 除非确切的文本是必要的证据,否则不要粘贴原始 shell 输出。
- 保持证据简洁:命令名称、仓库相对路径、总结结果或小的嵌套证据要点(当更易于扫描时)。
- 仅在失败的尝试影响下一个可重新启动步骤时才记录。
- 将任务验证与预先存在的仓库债务或不相关的警告分开。
- 优先选择更少、更密集的块,而不是许多微块。
- 使用现有任务的语言和语气。编写自然的要点,包括结果、紧凑的证据以及仅在必要时保留的剩余重新启动条件。
对于 logs/DECISIONS.md:
- 仅记录影响未来解释、范围、架构、回滚或规则应用的决策。
- 不要记录常规编辑、验证通过、文件创建或明显的实现步骤。
- 将每个块保留为 4 个要点:
背景、决策、原因、影响。 - 当工作暂停、被拒绝或转换为仅参考状态时,在
DECISIONS.md或BRIEF.md的紧凑当前状态中记录最终决策和重新打开条件。
对于两个日志:
- 使用
**YYYY-MM-DD**在带日期的部分下添加条目。 - 保持语言与现有任务一致;否则使用当前用户语言。
- 对于日志写入,默认解析技能相关的
scripts/task_logs.py路径并使用其append入口点。如果不可用,手动追加,保持相同的块形状。
路径和所有权规则
- 使用仓库相对路径或占位符,如
<repo-root>、<task-root>和$CODEX_HOME;绝不使用用户特定的绝对路径。 - 绝不要存储机密。
- 父代理拥有
BRIEF.md和规范日志。 - 除非明确分配了规范回写,否则子代理仅写入临时笔记或工件。
- 子代理从无继承上下文开始;传递一个简短的摘要:目标、最新用户约束、边界说明、未验证的假设或未知、验证命令、工件路径。
操作模型
-
读取可复用上下文。
- 对活动主题使用
rg在docs/reference/**/*.md中。 - 从最接近任务的最多 3 个窄参考文件开始。
- 在创建新参考或可能继续工作的新任务之前,检查最接近的项目上下文接口,查找相同未解决的工作或可复用的当前上下文。
- 如果代码、API、配置、测试或显式命名的外部所有者是权威的,则链接到该所有者而不是重述;保持项目上下文内容为任务特定的恢复或路由上下文。
- 对活动主题使用
-
检查一个相关任务。
- 首先读取
BRIEF.md。 - 仅当摘要仍然匹配相同的未完成工作时才打开日志。
- 首先读取
-
决定复用或新任务。
- 仅在未解决的工作和预期输出仍然匹配时复用。
- 使用边界说明作为提示,而不是任务标识。
- 否则启动一个新的带日期任务。
-
确保任务外壳。
- 如果需要持久上下文并且仓库实际上是空的,则创建
docs/reference/和一个带BRIEF.md和日志的带日期任务。 - 对于大多数写入型任务,创建或更新一个带日期的任务。
- 仅对非常小、低判断、立即完成的更改跳过任务创建。
- 如果需要持久上下文并且仓库实际上是空的,则创建
-
写入规范接口。
- 原地重写
BRIEF.md。 - 追加决策和工作日志条目。
- 仅将可复用的当前规则或可靠事实移入
docs/reference/**;将调查、进度和一次性任务状态保留在任务局部接口中。 - 在创建或实质性编辑任何任务文档后,重新检查任务根目录所有权。
- 原地重写
-
仅在需要时添加可选接口。
- 仅当一个下一步不够时,添加任务局部待办事项。
- 仅对非活动的未来工作保留仓库待办事项。
- 不要在摘要、待办事项、工作笔记和日志之间镜像开放工作。
-
如果上下文缺失,使用显式假设继续,并在执行后记录更正。
反模式
- 为只读或一次性工作初始化项目上下文文件。
- 由于主题相似而非相同未解决工作而复用任务。
- 将
BRIEF.md变成追加历史、可复用文档、验证笔记、文件清单或理由。 - 让
范围变成已接触文件列表。 - 让
当前状态叙述工作序列而不是可恢复状态。 - 让
下一步变成待办事项。 - 让任务根目录变成混合仓库而不是当前规范文档和路由。
- 将
docs/reference/**变成调查笔记、进度或时间线叙述。 - 将
docs/reference/**变成代码清单、实现导览或当前源文件的目录。 - 创建通用溢出文件而不是按目的命名的任务局部文档。
- 在
docs/BACKLOG.md中保留已完成项。 - 在同一任务根目录混合规范文档、临时笔记和已完成遗留记录。
- 将原始命令记录、重复微步骤或嘈杂的 shell 输出转储到
WORKLOG.md中。 - 在
BRIEF.md和WORKLOG.md中重复相同的基准数字或验证矩阵,除非第二个接口添加了新解释。 - 将常规编辑或验证通过记录为决策。
- 保存绝对的用户特定路径或机密。
护栏检查
通过从已安装的 project-context 技能目录解析 scripts/check_runtime_shape.py 并从活动仓库根目录执行它来运行捆绑的检查器。如果从子目录运行,当嵌套的 docs 树可能混淆根目录检测时,传递 --repo-root <path>。
检查器仅涵盖运行时形态:必需文件、最新日志块形状、任务/参考路径标记和类似机密的标记。它不判断所有权、语义质量、完整历史、合并正确性或更广泛的范围纪律。
在最终确定之前:
- 如果
BRIEF.md包含禁止的章节、路径清单、进度叙述、类似待办事项的下一步或超出恢复所需的更多细节,则重写它。 - 如果根任务文档混合了当前规范文档与属于
working/、日志或archive/的草稿、报告、证据或过时计划,则将其重新分类。
最终检查
- 后续会话能否从
BRIEF.md重新打开工作而无需重建状态? - 可复用的当前上下文是否位于
docs/reference/**而不是任务日志中? - 执行和决策跟踪是否仅限于
logs/*.md? - 任务根目录是否仅包含当前规范文档和路由?
- 任务复用是否遵循未解决工作和预期输出而不是主题相似性?
- 如果
git status --short显示未跟踪的项目上下文文件,它们是否被有意保留、忽略或移入正确的任务/参考/归档接口? - 如果技能文件发生了更改,最终说明是否要么验证了已安装的/运行时副本,要么声明安装同步超出范围?
- 路径是否可移植且机密不存在?