53 lines
3.5 KiB
Markdown
53 lines
3.5 KiB
Markdown
|
# 文档索引 · 干什么事该看哪一篇（★ 2026-10-04 建）
|
|||
|
|
|
|||
|
|
> 🔴 **本档只解决一件事**：**别通读文档。** 按下表跳，⛔ 不许「先都读一遍」。
|
|||
|
|
> ⚠️ 落它的起因：文档已 14 篇 + `SKILL.md`，**改流程/改机制时不知道必看哪几篇**
|
|||
|
|
> ⇒ 出现过「**昨天写好的红线，今天换个会话又踩一遍**」（2026-10-03 立的「⛔ 写会怎样前先取证」，
|
|||
|
|
> 只躺在工作区日志里，换会话读不到 ⇒ 10-04 复发）。
|
|||
|
|
|
|||
|
|
## ⓿ 🔴 改流程／改机制前的**必读三篇**（顺序别换）
|
|||
|
|
|
|||
|
|
| 序 | 必读 | 读多久 | 为什么是它 |
|
|||
|
|
|---|---|---|---|
|
|||
|
|
| 1 | **`00-动手前必过.md`** | **3 分钟** | 六条动作红线。⛔ **开工前只读这一篇就够**，⛔ 别通读 pitfalls |
|
|||
|
|
| 2 | **`rules.md`** | 5 分钟 | 现行规则本体（⛔ 不是过程记录；历史在 `pitfalls.md`） |
|
|||
|
|
| 3 | **`manifest.md`** | 2 分钟 | 清单：哪些文件是什么、**哪个是权威**。⛔ 改之前先确认你改的那份是权威 |
|
|||
|
|
|
|||
|
|
**一句话**：⓿ 三篇加起来 **10 分钟**，能避开今天栽的每一类。
|
|||
|
|
|
|||
|
|
## 一、按「你要干什么」跳
|
|||
|
|
|
|||
|
|
| 你要干的事 | 必看 | ⛔ 不用看 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| **改流程／改机制／改正则** | `00-动手前必过.md` ＋ `rules.md` ＋ `manifest.md` | `pitfalls.md` 全篇 |
|
|||
|
|
| 说错了话、想找根因 | `pitfalls.md`（**按编号查**，⛔ 别通读） | — |
|
|||
|
|
| 常驻挂了／要开机自启 | `supervise-persistence.md`（唯一权威） | `architecture.md` |
|
|||
|
|
| 看板显示不对 | `collab-detail.md` | `architecture.md` |
|
|||
|
|
| 换机器／装钩子 | `deploy.md` ＋ `install.py` | 其余全部 |
|
|||
|
|
| 会话卡住／日志爆了／抢锁 | `SKILL.md` §1 加载块 | `pitfalls.md` |
|
|||
|
|
| 查某个历史会话干了啥 | `forensics.md` | — |
|
|||
|
|
| 任务图／多会话分工 | `taskgraph.md` ＋ `collab.md` | — |
|
|||
|
|
| 怎么回话／排版 | `03-回复排版-核心块.md` ＋ `02-功能优先协作协议.md` | — |
|
|||
|
|
| 对方甩来一句没头绪的话 | `02-功能优先协作协议.md` | — |
|
|||
|
|
| 只想要速查 | `99-速查清单.md` | — |
|
|||
|
|
| **问「这是什么、为什么这样」** | `architecture.md` | — |
|
|||
|
|
|
|||
|
|
## 二、🔴 文档四条规则（写文档／改文档时必守）
|
|||
|
|
|
|||
|
|
1. **分类索引** —— 新增文档必须在这张表里登记（⛔ 没登记 = 别人找不到 = 白写）。
|
|||
|
|
2. **结论在最前，过程记录在后** —— 读者要的是「现在是什么样」，⛔ 不是「我改了几轮」。
|
|||
|
|
3. **历史记录按时间倒排** —— **新的在前面，旧的在后面**（⛔ 追加只能往前插，⛔ 不许接在末尾）。
|
|||
|
|
4. **简明扼要有效** —— **单条 ≤6 KB**；⛔ 论证过程／对比表格／逐条展开全删；
|
|||
|
|
⚠️ 但**判据要点一个不许丢**（长度达标而判据被删 = **更坏**，那是假绿）。
|
|||
|
|
|
|||
|
|
## 三、🔴 为什么「存档」不等于「读得到」（10-04 实证）
|
|||
|
|
|
|||
|
|
| 档位 | 装什么 | 跨会话可见 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| `references/*.md` ＋ `SKILL.md` | **规矩** | ✅ 技能会自动加载 |
|
|||
|
|
| `.workbuddy/memory/<日期>.md` | **过程记录**（当天做了什么） | ❌ 只有那个工作区翻才看得到 |
|
|||
|
|
| 源码注释 ＋ git 历史 | 细节与来路 | ⛔ 没人会去看 |
|
|||
|
|
|
|||
|
|
⚠️ **10-04 的教训**：一条红线立在对的地方（工作区日志 197 KB），仍然等于没立
|
|||
|
|
⇒ **凡是「下次必须做到」的事，必须落在 `references/` 或 `SKILL.md`，⛔ 不能只写日志。**
|
|||
|
|
判据：`selftest.py::t_no_invented_consequence` 量的就是这个（红线在动手层**第一段**）。
|