project-context

项目上下文

目的

将持久的仓库上下文保存在普通文件中，以便后续会话无需重建状态即可继续工作。

将此技能用于恢复工作、交接、长期工作、子 Agent 后续跟进、可复用参考上下文或任务日志。不要为只读问题或一次性检查启动此流程。如果仓库已有上下文文档，但没有项目上下文目录结构，请明确决定是否采用现有文档，或先使用 project-context-migration，再创建并行目录树。

约定

docs/
  reference/**/*.md
  tasks/yyyy/mm-dd/<task-slug>/
    BRIEF.md
    logs/{DECISIONS,WORKLOG}.md
    [optional] <purpose-named-backlog>.md
    [optional] working/
    [optional] archive/
  [optional] BACKLOG.md

• docs/reference/** 用于存放可复用的当前规则和可靠事实。不要在其中记录调查历史、进度、时间线、代码清单或来源叙述。应指向权威代码、API、配置、测试或项目文档，而不是复述其内容。收到更正或删除请求时，应重写或移除过时内容。
• BRIEF.md 是仅通过重写更新的恢复卡：记录稳定的目标、范围边界、当前结论与状态，以及最近的可恢复步骤。它不是报告、历史记录、证据日志、文件清单或待办事项。在阶段交界处，应将其重写为新的恢复状态，并将此前的证据或时间线移至日志、working/ 或 archive/。
• logs/WORKLOG.md 按每个有意义且已完成的批次记录一条简明结果，而不是记录命令或细碎迭代。logs/DECISIONS.md 仅记录会改变后续解读、范围、架构、回滚或规则应用的决策。有决策需要记录之前，保持 DECISIONS.md 为空。具体的区块格式由随附的日志辅助工具负责。
• 任务根目录包含当前权威文档和路由文件。将持久、便于人阅读的草稿、调查笔记、未定计划、方法和精简的证据摘要保存在 working/ 中。将已完成、否决、替换或过时的上下文放入 archive/。
• 将一次性实验和浏览器测试代码、状态及原始输出保存在仓库外的隔离工作区中，检查后再丢弃。保留的代码和证据应归入仓库中相应的常规存放位置。
• 只有在一个最近步骤不足以说明工作时，才使用以任务命名的待办清单。将非活跃的仓库级工作保存在 docs/BACKLOG.md 中。

任务身份与共享归属

• 只有在未完成的工作和预期产出仍然一致时，才复用任务。主题相似或旧的边界说明不代表任务相同；不确定时，应创建一个新的、注明日期的任务。
• 当多个任务、负责人或阶段依赖某种会影响实现或验收的解读时，应指定一个当前权威归属。优先选择现有代码、API、配置、测试或项目文档作为归属。否则，任务特定的含义应归入以用途命名的任务根目录约定，可复用的含义应归入 docs/reference/**。
• 使用者应指向该权威归属，并仅保留任务特定的状态、差异和下一步行动。不要在简述、待办清单、工作笔记和日志中重复记录相同的未完成工作。

操作与验证

开始前，核对任务简述中的目标、当前状态和重启点。当当前状态表明目标已完成时，关闭所选任务；相邻的后续步骤则保留为候选项，直到用户或权威的已批准计划选定它们。

先阅读任务简述，只查阅执行所需的参考资料或日志上下文。复用匹配的未完成任务，或创建一个带核心文件的日期任务；仅当小型、无需过多判断的变更可立即完成时，才跳过新建任务。只有在存在不同的负责人或读者操作时，才添加可选内容。

为任务简述和规范日志指定一名撰写者。其他 Agent 只能在明确限定的任务分配下撰写这些内容。使用相对于仓库的路径或稳定占位符，不存储机密信息；委派工作时，只向受托方提供其所需的当前目标、约束、未知事项、证据命令、产物路径和规范指针。

当上下文缺失时，在可逆且明确说明的假设下继续；更改权限或作出难以撤销的承诺前，先行询问。

使用捆绑的日志辅助工具和运行时结构检查器；具体操作方式以其脚本为准。例行完成或交接时，运行相对于技能目录的 scripts/check_runtime_shape.py --task-root docs/tasks/yyyy/mm-dd/<task-slug>；任务路径相对于检测到的仓库，或显式指定的 --repo-root。进行仓库范围的审计或迁移检查时，省略 --task-root。检查器会检查必要结构、最新日志区块、可移植路径和类似机密的标记，但不检查所有权、语义质量、完整历史或迁移正确性。维护任务时，只有当任务简述能够重新开启工作，且当前上下文只有一名明确负责人，才算完成。