project-doc

项目长期文档治理

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

核心原则

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

目标文档形态

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

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

PRODUCT.md 与 DESIGN.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 自检结果。

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