# Project Doc

> Project Doc is an Agent Skill for documents published in the neavo/LinguaGacha repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

使用此技能维护项目长期文档

- Skill name: `project-doc`
- Category: [Documents](https://www.openparable.com/skill/documents/1)
- Source: https://github.com/neavo/LinguaGacha/blob/HEAD/.codex/skills/project-doc/SKILL.md
- Repository: neavo/LinguaGacha (2,205 GitHub stars when collected)

## SKILL.md

# 项目长期文档治理

把这个技能当作长期文档的治理器，而不是写作模板。目标不是让文档更满，而是让未来维护者更少误判：每条稳定规则都只有一个权威归宿，每次改动都能减少重复、错位、过期和低密度内容。

## 核心原则

- 优先删除、合并、迁移和压缩，只有证据充分且会影响未来维护判断时才补写。
- 写给未来任务使用，不记录本轮过程、历史迁移、临时方案、阶段性计划或“为什么这次这么改”。
- 只保留无法从代码、目录、类型名、局部实现或现有权威文档直接看出的稳定事实。
- 用当前有效系统边界组织内容，不沿用过期目录名、旧实现叙事或临时过渡口径。
- 同一业务语义只允许一个权威来源，其它位置只保留必要引用或删除。

## 目标文档形态

长期维护与实现约束只收口到：

```text
AGENTS.md
docs/
  ARCHITECTURE.md
  CLI.md
  BACKEND.md
  FRONTEND.md
  WORKFLOW.md
```

`PRODUCT.md` 与 `DESIGN.md` 由其它流程负责管理，不属于本技能的长期文档范畴。遇到产品语义或设计权威相关内容，只能提醒需要走对应流程，不要用本技能擅自修改或吸收。生成物、归档、任务临时文档、外部规范镜像、用户明确保留的计划材料和有独立生命周期的样例文件，也不自动吸收为长期权威文档。

## 收录闸门

一条信息必须同时满足四项才进入长期文档：

| 判断问题 | 不满足时 |
| --- | --- |
| 不知道它会改错落点、边界、契约或验证吗？ | 删除 |
| 它无法从代码、目录、类型名或局部实现直接看出吗？ | 删除 |
| 它描述当前稳定事实，而不是历史过程、本次改动或临时状态吗？ | 删除或改写 |
| 它有且只有一个固定归宿吗？ | 拆分、合并、迁移或删除 |

新增内容必须替换、合并、迁移或压缩既有信息，或补上会导致维护误判的真实缺口。只是“更完整”“更保险”“顺便提醒”的内容不写。

## 唯一归宿

| 信息回答的问题 | 唯一归宿 |
| --- | --- |
| Agent 如何协作、编码和交付 | `AGENTS.md` |
| 系统如何分层、跨层边界、运行时主链路和专题边界地图在哪里 | `docs/ARCHITECTURE.md` |
| CLI 命令模式、入口分发、命令协议、临时工程、资源注入、输出和平台启动器是什么 | `docs/CLI.md` |
| 后端公开协议、HTTP / SSE、bootstrap、topic、错误码和 write 契约是什么 | `docs/BACKEND.md` |
| 后端领域边界、状态拥有者、唯一写入口、数据库和 `.lg` 物理存储落点是什么 | `docs/BACKEND.md` |
| Electron、preload、renderer、`ProjectStore`、导航和样式消费边界是什么 | `docs/FRONTEND.md` |
| 任务起手式、验证矩阵、文档同步和交付自检是什么 | `docs/WORKFLOW.md` |

如果一段内容同时属于多个归宿，拆开。若同一规则出现在多个归宿，只保留权威版本，其它位置改成短引用或删除。

## 工作流

执行文档任务时按这个顺序推进：

1. 定义信息集合：列出本轮要处理的规则、入口、链接、表格、章节或叙事。
2. 判定归宿：为每条信息选择唯一归宿，没有归宿的信息不进入长期文档。
3. 先减后增：依次删除不合格内容、合并重复规则、迁移错位信息、压缩低密度叙事。
4. 补写缺口：只根据当前代码、现有权威文档或用户明确确认补写稳定事实。
5. 校验边界：检查文档地图、链接、脚本提示、测试断言和交付要求是否仍指向目标形态。
6. 回看 diff：确认命名、章节、引用和权威边界没有制造新的并行规则。

结构性文档任务如果没有发生删除、合并、迁移或压缩，默认没有完成，除非能说明现有文档已经干净，只剩必要补写。

## 文档组织规则

各归宿都按“未来维护要先判断什么”组织，不按历史来源、源码目录或本轮任务过程机械铺陈。

### `AGENTS.md`

- 保留：代理协作、仓库级硬约束、编码约束和交付硬约束。
- 避免：展开专题正文，专题规则应指向对应文档。

### `docs/ARCHITECTURE.md`

- 保留：系统分层、跨层边界、运行时主链路、专题边界地图和模块关系。
- 避免：平铺协议字段、状态表、设计规则或验证矩阵，它是专题边界地图，不是专题正文合集。

### `docs/CLI.md`

- 保留：文件进出型 CLI 命令模式、`--cli` 分发、平台可执行入口、命令参数边界、同步 job、临时 `.lg` 工程、外部资源注入、输出语义、退出码和打包启动器规则。
- 说明：CLI 如何作为产品入口适配器进入 Core，如何隐藏内部工程并复用任务链路。
- 避免：承载 HTTP / SSE 协议、数据库 schema、renderer 运行态、用户长教程或 Wiki 镜像。

### `docs/BACKEND.md`

- 保留：后端公开协议、领域边界、状态落点、唯一写入口、数据库与 `.lg` 物理存储规则。
- 组织：
  - 公开协议边界：API Gateway、HTTP / SSE、bootstrap、topic、错误码、同步 write、响应壳和前端可见事件。
  - 后端领域边界：Electron main 中 project、task、task-engine、task-worker、file、model、service 等领域的职责分界。
  - 状态与写入口：状态拥有者、唯一写入口、跨线程 / 跨模块 / 跨前后端载荷规则。
  - 物理存储落点：SQL、事务、`.lg` asset、migration、Zstd 压缩工具和文件格式分发的固定位置。
  - 典型后端链路：只保留会影响维护判断的协议到领域服务、任务引擎、数据库 workflow 的流转事实。
  - 更新触发条件：哪些协议、状态、数据库、任务或文件格式变化必须同步更新本文。
- 避免：写成接口字段大全或数据库实现说明书，字段级细节、局部算法和能从类型定义直接看出的内容，优先留在代码和测试中。

### `docs/FRONTEND.md`

- 保留：Electron / preload / renderer / `ProjectStore` / 导航 / 样式消费边界。
- 说明：前端如何接入宿主与后端、状态如何落地、页面如何消费运行态。
- 避免：承载后端协议权威，或替代产品与设计流程。

### `docs/WORKFLOW.md`

- 保留：任务起手式、阅读路径、验证矩阵、文档同步规则和交付自检。
- 避免：复述各专题正文，它描述执行顺序和验证选择。

## 必须重组的信号

出现下面任一信号，重写相关信息块，不要局部补一句：

- 同一主题在一份文档或多份文档中重复出现。
- 新规则只能靠“补充、另外、注意、同时”塞进去。
- 章节名、目录划分或叙事方式仍在解释不再成立的系统形态。
- 表格和列表继续变长，但没有改变维护判断。
- `AGENTS.md` 承担专题正文，或专题文档反向承载协作规则。
- 文档按照历史来源分组，而不是按照当前权威归宿和未来阅读路径分组。

## 证据规则

- 代码是真相来源，但长期文档只记录代码表面无法可靠传达的维护规则。
- 现有权威文档可作为证据，但发现冲突时必须回到代码或用户确认。
- 用户明确确认可作为证据，把确认后的当前事实写入归宿，不写对话过程。
- 证据不足的问题列为未决，不写成长期规则。

## 删除前检查

删除遗留文档、并行文档、入口文件或大段正文前，必须确认：

- 稳定规则已经进入唯一归宿，或已判定不满足收录闸门。
- 仓库内链接、脚本报错、README、测试断言和技能提示不再指向被删除入口。
- 它不是工具链入口、外部流程入口、用户指定保留文件或生命周期未明的证据材料。
- 删除后文档地图仍能让未来任务找到正确阅读路径。

## 交付格式

交付时只汇报信息集合变化：

- 删除：删掉了哪些不合格信息、重复正文或旧入口。
- 合并：哪些重复规则被收成唯一权威。
- 迁移：哪些信息移动到哪个归宿。
- 压缩：哪些长段、表格或历史叙事被压成判断规则。
- 补写：补了什么缺口，证据是什么。
- 保留：看似可疑但仍保留的理由。
- 未决：证据不足而没有写入长期文档的问题。
- 验证：目标文档形态、链接、引用、脚本提示、测试断言和 diff 自检结果。

若交付主要是新增内容，必须说明它替换、合并、迁移或压缩了什么，否则视为只增不减。

---

Source: https://www.openparable.com/skill/documents/project-doc (OpenParable). Cite the canonical URL above.