project-context-setup

项目上下文设置

搭建仓库本地上下文文件，让 Agent 工作流在不同会话间保持一致： 问题跟踪规则、分类标签、领域术语表布局、ADR 布局、Agent 简报格式， 以及范围外事项记忆。

适用场景

使用此技能	使用其他包
仓库缺少 docs/agents/ 上下文文件	使用 adr-writer 处理单个架构决策
Agent 需要统一的领域词汇	使用 task-decomposer 处理已确定范围的功能
分类或发布问题需要标签规范	使用 github 执行直接的 GitHub CLI 操作
多 Agent 工作需要持久的问题简报	使用 handoff 编写仅限当前会话的续接说明

参考文件

文件	内容	加载时机
references/context-format.md	CONTEXT.md 和 CONTEXT-MAP.md 术语表格式	创建或编辑领域文档时
references/agent-brief.md	持久的 ready-for-agent 问题简报约定	准备问题交接时
references/out-of-scope.md	对被拒绝增强功能的持久记忆	分类涉及 wontfix 决策时

核心工作流

1. 探查

写入前检查仓库的实际状态：

• 检查 git remote -v 和 .git/config，查找问题跟踪器线索
• 检查根目录中的 AGENTS.md 和 CLAUDE.md
• 检查根目录中的 CONTEXT.md 和 CONTEXT-MAP.md
• 检查 docs/adr/ 和上下文范围内的 ADR 目录
• 检查现有的 docs/agents/
• 检查现有的 .out-of-scope/

报告已有和缺失的内容。不要盲目覆盖现有文件。

2. 选择设置值

与用户确认这些值，或根据明确的仓库证据确定：

决策	默认值	输出
问题跟踪器	如果存在 GitHub 远程仓库，则使用 GitHub；否则使用本地 Markdown	docs/agents/issue-tracker.md
分类标签	规范标签与角色名称一致	docs/agents/triage-labels.md
领域文档	单一根上下文	docs/agents/domain.md
Agent 指令文件	优先使用现有的 AGENTS.md，否则使用现有的 CLAUDE.md	更新 ## Agent context 区块

如果 AGENTS.md 和 CLAUDE.md 都存在，则更新 AGENTS.md，以便跨 Agent 使用。 如果两者都不存在，则先询问再创建。

3. 编写上下文文件

创建或更新以下文件：

docs/agents/
├── issue-tracker.md
├── triage-labels.md
└── domain.md

遵循以下规范：

• 问题跟踪器说明应具备可操作性：写明准确的 CLI、标签修改策略，以及 Agent 是否可以评论或关闭问题。
• 将规范分类角色映射到实际标签。仓库已有等效标签时，不要创建重复标签。
• 说明仓库采用单一根 CONTEXT.md，还是采用包含各上下文术语表的 CONTEXT-MAP.md。
• 记录 ADR 查找规则。全局决策使用 docs/adr/，存在上下文级 ADR 目录时则使用这些目录。

4. 添加 Agent 上下文区块

在选定的指令文件中添加或更新此区块：

## Agent context

### Issue tracker

See `docs/agents/issue-tracker.md` for where issues live and which operations agents may perform.

### Triage labels

See `docs/agents/triage-labels.md` for canonical triage roles and their concrete label strings.

### Domain docs

See `docs/agents/domain.md` for `CONTEXT.md`, `CONTEXT-MAP.md`, and ADR lookup rules.

如果区块已存在，则原位更新。不要追加重复区块。

5. 可选领域术语表

仅当用户至少确认了一个领域术语时，才创建 CONTEXT.md。使用 references/context-format.md。不要填入通用编程概念。

仅当多上下文仓库需要单独的术语表时，才创建 CONTEXT-MAP.md。

验证

• docs/agents/issue-tracker.md 存在，并说明跟踪器、允许的操作和必需工具。
• docs/agents/triage-labels.md 映射 needs-triage、needs-info、ready-for-agent、ready-for-human 和 wontfix。
• docs/agents/domain.md 说明单上下文或多上下文布局，以及 ADR 查找规则。
• 选定的指令文件中恰好包含一个 ## Agent context 区块。
• 保留该区块之外现有的用户编写内容。