# ERRORS 目录使用说明

本目录每个 `ERR-YYYYMMDD-NNN-<slug>.md` 是一条独立的错误日志。**文件名本身就是索引**——日期 + 当天序号 + 主题 slug，无需额外维护汇总文件（历史 `INDEX.md` 已删除，原因见下方）。

新建条目格式见 [`.agents/skills/self-improving-agent/SKILL.md`](../../.agents/skills/self-improving-agent/SKILL.md) § Error 条目。

---

## 怎么找想要的 ERR

### 按时间倒序看最新 N 条

```bash
ls .learnings/ERRORS/ | grep '^ERR-' | sort -r | head -20
```

### 按主题关键字搜

```bash
# 标题级
grep -lE 'prisma|db push' .learnings/ERRORS/*.md

# 全文
grep -rnE 'P1014|migration drift' .learnings/ERRORS/
```

### 看某一天/某段日期的所有 ERR

```bash
ls .learnings/ERRORS/ERR-202605*       # 2026 年 5 月全部
ls .learnings/ERRORS/ERR-20260519-*    # 2026-05-19 当天
```

### Gitea 网页

打开 [.learnings/ERRORS/](http://43.130.59.228/FFAIWorkspace/workspace/src/branch/develop/.learnings/ERRORS)，文件列表已按文件名（含日期）排序。

---

## 文件命名规范

```
ERR-YYYYMMDD-NNN-<short-kebab-slug>.md
```

- `YYYYMMDD`：发生/沉淀日期，**绝对**日期（不是相对）
- `NNN`：当天 ERR 序号，零填充三位（`001`, `002`, ...）
- `<short-kebab-slug>`：3-6 个英文单词，连字符分隔，描述核心症状

示例：
- `ERR-20260101-003-some-feature-bug.md` ✅（示例日期，避开真实文件撞车）
- `ERR-20260519-001-daemon-host-not-git-repo.md` ✅
- `ERR-20260519-2.md` ❌（缺 slug + 序号没零填充）
- `ERR-prisma-issue.md` ❌（缺日期）

---

## 同日多人/多 PR 并行：避免编号撞车

不同 PR 在同一天独立沉淀 ERR 时，编号可能撞（你写 `-001`、我也写 `-001`）。**写之前先 ls 看当天最大编号**：

```bash
# 写新 ERR 前先看当天已有几个
ls .learnings/ERRORS/ERR-$(date +%Y%m%d)-* 2>/dev/null
```

如果先后两个 PR 都用了相同编号，**后合并的那个 PR 必须重命名 + 改所有引用**（参考 [PR #446 / PR #444 编号冲突的处理过程](http://43.130.59.228/FFAIWorkspace/workspace/pulls/446)）。

---

## 为什么不再维护 `INDEX.md`

旧设计每加一条 ERR 都要：
1. 新建 `ERR-*.md` 文件
2. 在 `INDEX.md` prepend 一行索引（"- [ERR-id](id.md) — 一句话摘要"）
3. 修改 `INDEX.md` 顶部「共 N 条」计数

第 2、3 步让 `INDEX.md` 成为**共享 mutable 文件**——多 PR 并行写**必然冲突**。AI 高频合并节奏下每个 ERR 沉淀 PR 都要 rebase + 解 INDEX 冲突，PR 经常因为 INDEX 撞车被 daemon 卡 outdated 几轮。

切换到「文件名即索引」后：
- 每个 ERR 是独立新文件，没有任何"共享文件需要 prepend"
- 完全无冲突点
- 查找用 `ls` / `grep`（上面有示例），跟 `INDEX.md` 那一行摘要等效
- Gitea 网页目录视图也是天然索引

历史背景：
- 最早是单文件 `ERRORS.md`（issue #189 拆分为多文件 + INDEX.md）
- INDEX.md 撞车反复发生（PR #446 在一天内被同根因卡 3 次）
- 2026-05-19 在 PR #446 期间彻底删除（issue #456 讨论 + 同 PR 决策）