From 647621e5ea3c53f5acde0895e7e0de1417263243 Mon Sep 17 00:00:00 2001 From: yuxuanhui Date: Mon, 7 Sep 2026 16:27:09 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E4=BB=A3=E7=90=86?= =?UTF-8?q?=E6=8A=80=E8=83=BD=E6=96=87=E6=A1=A3=EF=BC=8C=E5=8C=85=E6=8B=AC?= =?UTF-8?q?=E9=97=AE=E9=A2=98=E8=B7=9F=E8=B8=AA=E5=99=A8=E3=80=81=E5=88=86?= =?UTF-8?q?=E8=AF=8A=E6=A0=87=E7=AD=BE=E5=92=8C=E9=A2=86=E5=9F=9F=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 13 ++++++++++++ docs/agents/domain.md | 32 +++++++++++++++++++++++++++++ docs/agents/issue-tracker.md | 40 ++++++++++++++++++++++++++++++++++++ docs/agents/triage-labels.md | 14 +++++++++++++ 4 files changed, 99 insertions(+) create mode 100644 AGENTS.md 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 new file mode 100644 index 0000000..c1af51d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,13 @@ +## Agent skills + +### Issue tracker + +任务使用本地 Markdown 跟踪。创建、读取或更新任务与规格前，阅读 `docs/agents/issue-tracker.md`。 + +### Triage labels + +使用五个默认 triage 标签。分类或变更任务分诊状态前，阅读 `docs/agents/triage-labels.md`。 + +### Domain docs + +采用 single-context 布局。探索代码库前，阅读 `docs/agents/domain.md`，并按其规则加载领域文档。 diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..6086c46 --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,32 @@ +# Domain Docs + +本仓库采用 single-context 布局： + +- 根目录 `CONTEXT.md`：领域术语及模型。 +- `docs/adr/`：架构决策记录。 + +## 探索前读取 + +探索代码库前，阅读根目录 `CONTEXT.md`， +以及 `docs/adr/` 中与当前工作相关的决策。 + +若将来存在根目录 `CONTEXT-MAP.md`， +先按其中索引读取相关上下文的 CONTEXT.md 和 ADR。 + +文档不存在时直接继续，无需报告缺失或建议提前创建。 +领域术语和决策实际明确后，由 `/domain-modeling` +按当前任务授权按需创建。 + +## 使用领域词汇 + +任务标题、重构建议、假设和测试名称中的领域概念， +使用 CONTEXT.md 已定义的术语。 + +遇到尚未收录的概念，先核对项目现有用语； +确有缺口时，将其作为当前任务中供 `/domain-modeling` +处理的候选。 + +## 揭示决策冲突 + +建议或实现方向与现有 ADR 冲突时， +明确指出 ADR 编号、冲突内容及重新讨论的理由。 diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..64b68b8 --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,40 @@ +# Issue tracker: Local Markdown + +本仓库的任务与规格存放在 `.scratch/`。 + +## 文件约定 + +- 每个功能一个目录：`.scratch//`。 +- 规格：`.scratch//spec.md`。 +- 实现任务：`.scratch//issues/-.md`， + 从 `01` 编号，每个任务独立一个文件。 +- 分诊状态记录在任务文件顶部附近的 `Status:` 行， + 取值参见 `triage-labels.md`。 +- 评论与讨论历史追加在文件底部的 `## Comments` 下。 + +## 发布与读取 + +技能要求“发布到 issue tracker”时，在上述约定路径创建文件， +按需创建目录。 + +技能要求“获取相关 ticket”时，读取用户指定路径； +若只提供编号，则在对应功能的 issues 目录中定位文件。 +编号存在歧义时，先确认所属功能。 + +## Wayfinding + +以下约定供 `/wayfinder` 使用： + +- 总览：`.scratch//map.md`， + 包含 Notes、Decisions-so-far 和 Fog。 +- 子任务：`.scratch//issues/NN-.md`， + 从 `01` 编号，正文记录待解决问题。 +- `Type:` 取值为 research、prototype、grilling 或 task。 +- Wayfinding 使用独立的工作状态： + `Status: open`、`Status: claimed`、`Status: resolved`。 +- 依赖记录为 `Blocked by: NN, NN`； + 所有依赖均 resolved 后，任务才解除阻塞。 +- 下一个任务：按编号选择 open 且未被阻塞的任务。 +- 领取：开始工作前写入 `Status: claimed`。 +- 完成：在 `## Answer` 下追加答案，写入 `Status: resolved`， + 并向 map.md 的 Decisions-so-far 追加摘要和任务链接。 diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md new file mode 100644 index 0000000..fe98ab7 --- /dev/null +++ b/docs/agents/triage-labels.md @@ -0,0 +1,14 @@ +# Triage Labels + +本地任务的 `Status:` 使用以下分诊标签。 +技能提及规范角色时，使用表中对应值。 + +| 规范角色 | 本仓库标签 | 含义 | +| --- | --- | --- | +| needs-triage | needs-triage | 等待维护者评估 | +| needs-info | needs-info | 等待补充信息 | +| ready-for-agent | ready-for-agent | 规格完整，可由代理实现 | +| ready-for-human | ready-for-human | 需要人工实现 | +| wontfix | wontfix | 不予处理 | + +Wayfinding 的领取与完成状态遵循 `issue-tracker.md` 中的独立约定。