From f6166d3b20b0ac952dc6ff3c51979f76129fd23f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=91=A8=E8=A1=8C=E5=AD=90?= Date: Mon, 20 Jul 2026 05:30:56 +0800 Subject: [PATCH] docs: configure agent skills --- AGENTS.md | 14 +++++++++++ docs/agents/domain.md | 34 +++++++++++++++++++++++++++ docs/agents/issue-tracker.md | 45 ++++++++++++++++++++++++++++++++++++ docs/agents/triage-labels.md | 15 ++++++++++++ 4 files changed, 108 insertions(+) create mode 100644 docs/agents/domain.md create mode 100644 docs/agents/issue-tracker.md create mode 100644 docs/agents/triage-labels.md diff --git a/AGENTS.md b/AGENTS.md index 6f02427..b2d75dc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,3 +44,17 @@ - 当代码或配置变更导致本文件中的命令、路径或约定失效时，在同一任务中更新本文件。 - 将重复出现的错误假设或评审反馈写入适用范围最近的 `AGENTS.md`；仅在需要临时替换同目录规则时使用 `AGENTS.override.md`。 - 完成任务后报告修改文件、执行的命令、结果和剩余风险。 + +## Agent skills + +### 议题跟踪器 + +议题和 PRD 统一记录在本仓库的 GitHub Issues 中。详见 `docs/agents/issue-tracker.md`。 + +### Triage 标签 + +使用五个默认 triage 标签，不设置覆盖映射。详见 `docs/agents/triage-labels.md`。 + +### 领域文档 + +本仓库采用 single-context 布局，在仓库根目录维护 `CONTEXT.md` 和 `docs/adr/`。详见 `docs/agents/domain.md`。 diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..ddab4d8 --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,34 @@ +# 领域文档 + +本文件说明工程 Skills 在探索代码库时应如何使用本仓库的领域文档。 + +## 探索前读取 + +- 仓库根目录的 **`CONTEXT.md`**。 +- **`docs/adr/`**：读取与即将处理区域相关的 ADR。 + +如果上述文件或目录不存在，**直接继续，不作提示**。不要将缺失视为问题，也不要预先建议创建。`/domain-modeling` Skill（可通过 `/grill-with-docs` 和 `/improve-codebase-architecture` 进入）会在术语或决策真正明确时按需创建这些文件。 + +## 文件结构 + +本仓库采用 single-context 布局： + +```text +/ +├── CONTEXT.md +├── docs/ +│ └── adr/ +└── src/ +``` + +## 使用术语表中的词汇 + +输出中提及领域概念时——例如议题标题、重构提案、假设或测试名称——使用 `CONTEXT.md` 定义的术语。不要改用术语表明确排除的同义词。 + +如果术语表尚未包含所需概念，这通常意味着两种情况之一：正在创造项目并未使用的词汇，应重新考虑；或者确实存在领域空白，应记录下来交由 `/domain-modeling` 处理。 + +## 标明与 ADR 的冲突 + +如果输出与现有 ADR 冲突，应明确指出，而不是静默覆盖： + +> _与 ADR-0007 冲突——但值得重新讨论，因为……_ diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..52d0f5b --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,45 @@ +# 议题跟踪器：GitHub + +本仓库的议题和 PRD 记录在 GitHub Issues 中。所有操作均使用 `gh` CLI。 + +## 约定 + +- **创建议题**：`gh issue create --title "..." --body "..."`。多行正文使用 heredoc。 +- **读取议题**：`gh issue view --comments`；使用 `jq` 筛选评论时，同时获取标签。 +- **列出议题**：`gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'`，并按需添加 `--label` 和 `--state` 筛选条件。 +- **评论议题**：`gh issue comment --body "..."` +- **添加或移除标签**：`gh issue edit --add-label "..."` / `--remove-label "..."` +- **关闭议题**：`gh issue close --comment "..."` + +通过 `git remote -v` 推断仓库；在克隆仓库内运行时，`gh` 会自动完成推断。 + +## 将拉取请求作为 triage 入口 + +**PRs as a request surface: no（不将 PR 作为请求入口）。** _（如果本仓库将外部 PR 视为功能请求，可改为 `yes`；`/triage` 会读取此标志。）_ + +设置为 `yes` 后，PR 使用与议题相同的标签和状态流转，并改用对应的 `gh pr` 命令： + +- **读取 PR**：`gh pr view --comments`，并使用 `gh pr diff ` 查看差异。 +- **列出待 triage 的外部 PR**：运行 `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments`，只保留 `authorAssociation` 为 `CONTRIBUTOR`、`FIRST_TIME_CONTRIBUTOR` 或 `NONE` 的 PR，排除 `OWNER`、`MEMBER` 和 `COLLABORATOR`。 +- **评论、添加标签或关闭**：使用 `gh pr comment`、`gh pr edit --add-label` / `--remove-label` 和 `gh pr close`。 + +GitHub 的议题与 PR 共用同一编号空间，因此单独的 `#42` 可能指向其中任意一种对象；先运行 `gh pr view 42`，失败后再运行 `gh issue view 42`。 + +## 当 Skill 要求“publish to the issue tracker（发布到议题跟踪器）”时 + +创建一个 GitHub Issue。 + +## 当 Skill 要求“fetch the relevant ticket（获取相关任务单）”时 + +运行 `gh issue view --comments`。 + +## Wayfinding 操作 + +供 `/wayfinder` 使用。**地图（map）**是一个单独的议题，**子议题（child）**是具体任务单。 + +- **地图**：一个带有 `wayfinder:map` 标签的议题，其正文维护 Notes / Decisions-so-far / Fog。使用 `gh issue create --label wayfinder:map` 创建。 +- **子任务单**：通过 GitHub 子议题关联到地图（使用 `gh api` 调用 sub-issues 端点）。如果仓库未启用子议题，则将子任务添加到地图正文的任务列表，并在子任务正文顶部写入 `Part of #`。标签使用 `wayfinder:`，其中类型为 `research`、`prototype`、`grilling` 或 `task`。任务被领取后，将其分配给负责推进的开发者。 +- **阻塞关系**：GitHub 原生 issue dependencies 是规范且在界面中可见的表达方式。使用 `gh api --method POST repos///issues//dependencies/blocked_by -F issue_id=` 添加依赖边，其中 `` 是阻塞议题的数字数据库 ID，可通过 `gh api repos///issues/ --jq .id` 获取；它不是 `#number` 或 `node_id`。GitHub 通过 `issue_dependencies_summary.blocked_by` 报告尚未关闭的阻塞项，这是实时放行条件。如果依赖功能不可用，则在子任务正文顶部使用 `Blocked by: #, #`。所有阻塞议题关闭后，任务才算解除阻塞。 +- **前沿查询**：列出地图中尚未关闭的子任务（运行 `gh issue list --state open`，并限定在地图的子议题或任务列表内），排除仍有未关闭阻塞项（`issue_dependencies_summary.blocked_by > 0`，或 `Blocked by` 行引用了未关闭议题）或已有受理人的任务；按地图中的顺序选择第一个候选项。 +- **领取**：运行 `gh issue edit --add-assignee @me`；这是会话中的第一次写操作。 +- **解决**：运行 `gh issue comment --body ""`，再运行 `gh issue close `，最后在地图的 Decisions-so-far 中追加上下文指针（gist 及其链接）。 diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md new file mode 100644 index 0000000..5a4f538 --- /dev/null +++ b/docs/agents/triage-labels.md @@ -0,0 +1,15 @@ +# Triage 标签 + +这些 Skills 使用五个规范 triage 角色。本文件将这些角色映射到本仓库议题跟踪器实际使用的标签字符串。 + +| mattpocock/skills 中的标签 | 本仓库标签 | 含义 | +| -------------------------- | ----------------- | ---------------------------- | +| `needs-triage` | `needs-triage` | 需要维护者评估该议题 | +| `needs-info` | `needs-info` | 等待报告者提供更多信息 | +| `ready-for-agent` | `ready-for-agent` | 需求已完整，可交给 AFK Agent | +| `ready-for-human` | `ready-for-human` | 需要由人工实现 | +| `wontfix` | `wontfix` | 不会处理 | + +当 Skill 提到某个角色时（例如“应用可由 AFK Agent 处理的 triage 标签”），使用表中对应的标签字符串。 + +如果本仓库实际使用其他标签词汇，请修改右侧“本仓库标签”列。