Community写作与编辑github.com

perhapsspy/project-context

为 AI 编码助手提供的轻量级项目上下文技能,通过文件持久化仓库上下文。

project-context 是什么?

这是一个为 AI 编码助手(如 Claude Code, Cursor, Codex)设计的轻量级技能,核心目标是在普通文件中持久化仓库上下文,使得后续的会话或代理能够在无需重建状态的情况下无缝继续工作。它通过在仓库内定义一套严格的目录结构(`docs/reference/`、`docs/tasks/.../`)和核心文件(如 `BRIEF.md` 和日志)来管理上下文,避免依赖外部系统或隐藏记忆。该技能特别适用于需要跨线程或跨代理进行长周期工作、任务交接或维护可复用参考笔记的场景。其工作流程包括读取可复用上下文、检查相关任务、决策复用或新建任务,并严格规范了 `BRIEF.md` 的内容所有权和日志更新规则,以保持上下文的精炼和可恢复性。

兼容平台~Claude Code✓Codex CLI~Cursor
npx skills add perhapsspy/project-context

Installed? Explore more 写作与编辑 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

项目上下文

目的

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

使用 / 不使用

当仓库工作需要跨线程或跨代理的持久上下文时使用此技能:恢复或交接、长时间运行的工作、子代理跟进、可复用的参考笔记、当前任务摘要或仅追加的日志。

不要为只读问题、一次性检查或隐式迁移分散的旧文档进行初始化。如果布局缺失,请选择显式采用或迁移。

核心倾向

  • 优先使用普通仓库文件,而非外部系统或隐藏内存。
  • 当前可信主题上下文: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 和规范日志。
  • 除非明确分配了规范回写,否则子代理仅写入临时笔记或工件。
  • 子代理从无继承上下文开始;传递一个简短的摘要:目标、最新用户约束、边界说明、未验证的假设或未知、验证命令、工件路径。

操作模型

  1. 读取可复用上下文。

    • 对活动主题使用 rg 在 docs/reference/**/*.md 中。
    • 从最接近任务的最多 3 个窄参考文件开始。
    • 在创建新参考或可能继续工作的新任务之前,检查最接近的项目上下文接口,查找相同未解决的工作或可复用的当前上下文。
    • 如果代码、API、配置、测试或显式命名的外部所有者是权威的,则链接到该所有者而不是重述;保持项目上下文内容为任务特定的恢复或路由上下文。
  2. 检查一个相关任务。

    • 首先读取 BRIEF.md。
    • 仅当摘要仍然匹配相同的未完成工作时才打开日志。
  3. 决定复用或新任务。

    • 仅在未解决的工作和预期输出仍然匹配时复用。
    • 使用边界说明作为提示,而不是任务标识。
    • 否则启动一个新的带日期任务。
  4. 确保任务外壳。

    • 如果需要持久上下文并且仓库实际上是空的,则创建 docs/reference/ 和一个带 BRIEF.md 和日志的带日期任务。
    • 对于大多数写入型任务,创建或更新一个带日期的任务。
    • 仅对非常小、低判断、立即完成的更改跳过任务创建。
  5. 写入规范接口。

    • 原地重写 BRIEF.md。
    • 追加决策和工作日志条目。
    • 仅将可复用的当前规则或可靠事实移入 docs/reference/**;将调查、进度和一次性任务状态保留在任务局部接口中。
    • 在创建或实质性编辑任何任务文档后,重新检查任务根目录所有权。
  6. 仅在需要时添加可选接口。

    • 仅当一个下一步不够时,添加任务局部待办事项。
    • 仅对非活动的未来工作保留仓库待办事项。
    • 不要在摘要、待办事项、工作笔记和日志之间镜像开放工作。
  7. 如果上下文缺失,使用显式假设继续,并在执行后记录更正。

反模式

  • 为只读或一次性工作初始化项目上下文文件。
  • 由于主题相似而非相同未解决工作而复用任务。
  • 将 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 显示未跟踪的项目上下文文件,它们是否被有意保留、忽略或移入正确的任务/参考/归档接口?
  • 如果技能文件发生了更改,最终说明是否要么验证了已安装的/运行时副本,要么声明安装同步超出范围?
  • 路径是否可移植且机密不存在?

相关技能