---
name: issues-workflow
owner: team-lead
version: 1
last-updated: 2026-04-23
---

# SOP: issue 目录使用规范

`brain/issues/` 是**所有要做的事的队列源头**。发现任何 bug / 新需求 / 优化点 / 架构隐患 / 跨项目问题——**第一步立刻记 issue**，第二步才处理。

## 生命周期

```
  发现问题
     ↓
  立刻开 issue（brain/issues/NNN-<slug>.md）
     ↓
  刷 brain/issues/index.md 加一行（顶部）
     ↓
  评估优先级：
     ├─ 紧急阻塞 → 立刻做 → 补 in_progress 评论 → 做完 close+archive
     ├─ 非紧急    → 留 open，等老板拍 / 等合适时机
     └─ 明显不做 → close 说明原因 + archive
     ↓
  close 后 git mv 到 brain/issues/archive/
  刷 archive/index.md 加一行
```

## 建 issue 的时机（看到就建，不犹豫）

| 场景 | 该不该建 |
|---|---|
| 发现代码 bug | ✅ 建 |
| 发现架构隐患 / 技术债 | ✅ 建 |
| 有了新需求灵感 | ✅ 建 |
| 发现跨项目（vault / skill-pub / clawhub 等）的 bug | ✅ 建到**对方项目**的 issue 目录 |
| 发现文档错字 / 小拼写 | ⚠️ 看情况：直接 commit 修比建 issue 快时不建 |
| "我知道了还没来得及做" | ✅ 一定建——不建就忘 |

**不要用 "太小不值得" 作为不建的理由**。issue 是零成本的——建一个 issue 5 分钟，回头不做 close + archive 就行；不建 issue 忘了，事故来得多。

## 文件命名约定

- 路径：`brain/issues/<编号 3 位补零>-<英文 slug>.md`
- 编号：全项目单调递增，open 和 archive 共用编号空间
- slug：英文 kebab-case，描述核心动作（如 `epsilon-phone-salt-unset`、`github-skills-org-reorg`）

## frontmatter 必填字段

```yaml
---
id: NNN
title: 中文标题（能看懂是啥事）
status: open | in_progress | closed
labels: [infra, bug, tech-debt, ...]
assignee: team-lead | claude
created_at: YYYY-MM-DD
closed_at: YYYY-MM-DD   # close 时填
---
```

## 正文结构推荐

```markdown
## 场景 / 动机
  为什么这事重要 + 何时发现

## 方案选项
  A / B / C 各什么代价 + 倾向

## 推荐
  明确的下一步

## 代价 / 放弃
  选这个方案放弃了什么

## 讨论
  ### YYYY-MM-DD HH:MM @claude
  ...
  ### YYYY-MM-DD HH:MM @yarn
  ...

## 实施清单（如需要）
  - [ ] 步骤 1
  - [ ] 步骤 2
```

## 和别的事项的区别

- **TaskCreate**（session 内 task list）：当前对话里拆步骤用的。**跨 session 会丢**。发现问题 → 还是要建 issue，不是 task
- **decisions/**（ADR）：**已拍定的方向**。发现问题 → 不是 ADR。等方案拍定后，再从 issue 里抽出 ADR 到 decisions/
- **wiki/log.md**：运营日志 / 事故复盘。发现问题 → 不是日志。事后复盘进 log，立项进 issue

## 跨项目 issue

配合 [memories/feedback_all_projects_mine.md](~/.claude/memories/feedback_all_projects_mine.md)：跨项目主动管。但"管"的第一步仍是**记录到对方项目的 issue 目录**，例如：

- xiangqin 用 vault 时发现 vault bug → `~/vault/brain/issues/NNN-xxx.md`（不是 xiangqin 的 issue）
- xiangqin 里 grep "vault" 引用 → 记一个 reference 到 xiangqin 的 issue 说"依赖 vault#NNN 修复"

## 不做的反例

- ❌ "我先顺手修一下再说"（scope 蔓延 + 忘原任务）
- ❌ "太小不值得开 issue"（所有事都从 issue 入口）
- ❌ "我记在 task list 里就行"（session 结束就丢）
- ❌ "把多个问题塞一个 issue"（一件事一个 issue，大事拆 milestone）

## 归档

见 [archive/](archive/index.md)。
