| AGENTS.md | ●●●●● 补丁 | 查看 | 原始文档 | blame | 历史 | |
| CONTEXT.md | ●●●●● 补丁 | 查看 | 原始文档 | blame | 历史 | |
| docs/agents/domain.md | ●●●●● 补丁 | 查看 | 原始文档 | blame | 历史 | |
| docs/agents/issue-tracker.md | ●●●●● 补丁 | 查看 | 原始文档 | blame | 历史 | |
| docs/agents/triage-labels.md | ●●●●● 补丁 | 查看 | 原始文档 | blame | 历史 |
AGENTS.md
New file @@ -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`。 CONTEXT.md
New file @@ -0,0 +1,3 @@ # 项目领域上下文 （按需补充。） docs/agents/domain.md
New file @@ -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/ ``` docs/agents/issue-tracker.md
New file @@ -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 中追加上下文指针（摘要和链接） docs/agents/triage-labels.md
New file @@ -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 标签”），使用表中对应的标签字符串。 如果本仓库的标签词汇发生变化，编辑右侧“本仓库的标签”列。
