From 15e09c5ea3768f44265d97a7644fa2a384f4242e Mon Sep 17 00:00:00 2001
From: yeg <1347747024@qq.com>
Date: 星期五, 11 九月 2026 12:23:27 +0800
Subject: [PATCH] 项目文档

---
 docs/agents/triage-labels.md |   15 +++++++
 AGENTS.md                    |   13 ++++++
 docs/agents/domain.md        |   36 ++++++++++++++++++
 docs/agents/issue-tracker.md |   30 +++++++++++++++
 CONTEXT.md                   |    3 +
 5 files changed, 97 insertions(+), 0 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..1a3c7a1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,13 @@
+## Agent skills
+
+### Issue tracker
+
+Issue 以 Markdown 文件存放在 `.scratch/<feature-slug>/`。详见 `docs/agents/issue-tracker.md`。
+
+### Triage labels
+
+使用默认标签：`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix`。详见 `docs/agents/triage-labels.md`。
+
+### Domain docs
+
+采用单上下文布局：根目录 `CONTEXT.md`，ADR 位于 `docs/adr/`。详见 `docs/agents/domain.md`。
diff --git a/CONTEXT.md b/CONTEXT.md
new file mode 100644
index 0000000..77d9fca
--- /dev/null
+++ b/CONTEXT.md
@@ -0,0 +1,3 @@
+# 项目领域上下文
+
+（按需补充。）
diff --git a/docs/agents/domain.md b/docs/agents/domain.md
new file mode 100644
index 0000000..31fb031
--- /dev/null
+++ b/docs/agents/domain.md
@@ -0,0 +1,36 @@
+# 领域文档
+
+工程技能在探索代码库时应按以下规则读取领域文档。
+
+## 开始探索前读取
+
+- 根目录的 **`CONTEXT.md`**；或
+- 如果根目录存在 **`CONTEXT-MAP.md`**，读取它指向的、与当前主题相关的各个 `CONTEXT.md`；
+- **`docs/adr/`**：读取与即将处理区域相关的 ADR。在多上下文仓库中，还要检查 `src/<context>/docs/adr/` 下的上下文级决策。
+
+如果这些文件或目录不存在，静默继续。不要标记缺失，也不要提前建议创建；`/domain-modeling` 技能会在术语或决策真正确定时按需创建它们。
+
+## 使用术语表中的词汇
+
+当输出中出现领域概念（例如 issue 标题、重构提案、假设或测试名称）时，使用 `CONTEXT.md` 定义的术语。如果术语表明确避免使用某个同义词，不要改用该同义词。
+
+如果所需概念尚未出现在术语表中，这是一个信号：要么项目并不使用这个说法（应重新考虑），要么领域文档确实存在缺口（交由 `/domain-modeling` 记录）。
+
+## 标记 ADR 冲突
+
+如果输出与现有 ADR 冲突，应明确指出，而不是静默覆盖：
+
+> _与 ADR-0007 冲突（事件溯源订单），但值得重新打开，因为……_
+
+## 文件结构
+
+单上下文仓库（大多数仓库）：
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md
new file mode 100644
index 0000000..38ddc55
--- /dev/null
+++ b/docs/agents/issue-tracker.md
@@ -0,0 +1,30 @@
+# Issue 跟踪：本地 Markdown
+
+本仓库的 issue 和规格说明以 Markdown 文件存放在 `.scratch/` 中。
+
+## 约定
+
+- 每个功能使用一个目录：`.scratch/<feature-slug>/`
+- 规格说明文件为 `.scratch/<feature-slug>/spec.md`
+- 实现 issue 每个 ticket 使用一个文件：`.scratch/<feature-slug>/issues/<NN>-<slug>.md`，从 `01` 开始编号；不要合并为单个 tickets 文件
+- triage 状态记录在 issue 文件顶部附近的 `Status:` 行中（角色字符串见 `triage-labels.md`）
+- 评论和对话历史追加到文件底部的 `## Comments` 标题下
+
+## 技能要求“发布到 issue 跟踪系统”时
+
+在 `.scratch/<feature-slug>/` 下创建文件；目录不存在时一并创建。
+
+## 技能要求“获取相关 ticket”时
+
+读取引用的文件路径。用户通常会直接提供路径或 issue 编号。
+
+## Wayfinder 导航操作
+
+Wayfinder 使用一个 map 文件和每个 ticket 对应的子文件。
+
+- **Map**：`.scratch/<effort>/map.md`，正文包含 Notes、Decisions-so-far 和 Fog
+- **子 ticket**：`.scratch/<effort>/issues/NN-<slug>.md`，从 `01` 开始编号；正文中的 `Type:` 行记录 ticket 类型（`research`/`prototype`/`grilling`/`task`），`Status:` 行记录 `claimed`/`resolved`
+- **阻塞关系**：文件顶部附近的 `Blocked by: NN, NN` 行记录依赖。列出的所有文件都为 `resolved` 时，ticket 才算解除阻塞
+- **前沿 ticket**：扫描 `.scratch/<effort>/issues/`，查找未关闭、未阻塞且未认领的 ticket；优先选择编号最小者
+- **认领**：设置 `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..bf40ad9
--- /dev/null
+++ b/docs/agents/triage-labels.md
@@ -0,0 +1,15 @@
+# Triage 标签
+
+各技能使用五个规范化的 triage 角色。本文件将这些角色映射到本仓库 issue 跟踪系统中的实际标签字符串。
+
+| mattpocock/skills 中的标签 | 本仓库的标签 | 含义 |
+| --- | --- | --- |
+| `needs-triage` | `needs-triage` | 维护者需要评估此 issue |
+| `needs-info` | `needs-info` | 等待报告者补充信息 |
+| `ready-for-agent` | `ready-for-agent` | 规格完整，可交给 AFK agent |
+| `ready-for-human` | `ready-for-human` | 需要人工实现 |
+| `wontfix` | `wontfix` | 不会处理 |
+
+当技能提到某个角色时（例如“应用 AFK-ready triage 标签”），使用表中对应的标签字符串。
+
+如果本仓库的标签词汇发生变化，编辑右侧“本仓库的标签”列。

--
Gitblit v1.7.1