Yomiya Implementation Spec 拆分方案
Yomiya Implementation Spec 拆分方案
Section titled “Yomiya Implementation Spec 拆分方案”文档性质：实施规格文档治理与拆分方案
用途：把当前过重的 implementation spec 拆成可长期维护的文档体系
状态：当前有效
最后更新：2026-03-28
1. 为什么现在必须拆分
Section titled “1. 为什么现在必须拆分”当前 yomiya-implementation-spec.md 已经承载了过多角色，包括：
- 当前有效规格
- 自查报告
- 漏洞修复记录
- 深度排查结果
- 后续阶段定义
- 运营定义补充
- 附录式补丁决策
这会带来 4 个实际问题：
问题 1：主规格被历史痕迹污染
Section titled “问题 1：主规格被历史痕迹污染”研发或运营打开文档时，很难一眼判断：
- 什么是当前必须执行的最终规则
- 什么是审查过程中提出来的问题
- 什么是后续阶段再考虑的内容
问题 2：同一规则在多个位置重复出现
Section titled “问题 2：同一规则在多个位置重复出现”例如：
- Tab 分类逻辑
- collection 规则
- today featured 逻辑
- topic / scene / tag 关系
- 搜索、Push、播放模式等能力边界
一旦更新其中一处，其他位置很容易漏改。
问题 3：文档越来越像讨论记录，不像规格文件
Section titled “问题 3：文档越来越像讨论记录，不像规格文件”规格文档的职责是“给执行层明确答案”。 现在这份文档越来越像：
- 主规格
- RFC 讨论串
- 审核问题清单
- 修复补丁记录
- 未来规划草案
混在一起。
问题 4：Phase 1 边界容易失守
Section titled “问题 4：Phase 1 边界容易失守”当前 implementation spec 中已经包含大量：
- Phase 1 必做
- Phase 2 / 3 / 4 能力
- 暂未确认问题
- 未来增强项
这会不断诱导团队把未来阶段能力混进当前执行面。
2. 拆分后的目标状态
Section titled “2. 拆分后的目标状态”拆分后的目标不是“文件变多”，而是：
让每份文档只负责一件事，并且让读文档的人能迅速知道自己该看哪份。
最终要达到的状态：
- 产品 / 研发要开工时，只看当前有效规格
- 发现还有没定的问题时，看 open questions
- 回顾为什么之前做过某种调整时，看 review log
- 规划后续阶段时，看 future phases
3. 拆分后的文档结构
Section titled “3. 拆分后的文档结构”3.1 保留主规格文档
Section titled “3.1 保留主规格文档”product/yomiya-implementation-spec-core.md
这份文档只保留什么
Section titled “这份文档只保留什么”只保留当前有效且直接影响执行的最终规格，包括：
- 首页模块精确规格（仅当前版本）
- 首批合集规格（仅当前版本）
- 内容入库判断规则（当前生效版）
- LLM 打标 Prompt 规格（当前生效版）
- 数据结构（仅当前阶段确定会做的）
- 今日学习 / 学习进度定义（当前生效版）
- 标题处理规则（当前生效版）
- 封面获取与存储策略（当前生效版）
这份文档绝对不保留什么
Section titled “这份文档绝对不保留什么”- 自查报告
- 漏洞列表
- 修复记录
- 争议历史
- 未来阶段设计
- 还没定死的开放问题
主规格文档的标准
Section titled “主规格文档的标准”任何进入 *-core.md 的内容，都必须满足：
- 已经定稿
- 当前阶段会执行
- 研发 / 运营现在就需要知道
3.2 新建开放问题文档
Section titled “3.2 新建开放问题文档”product/yomiya-implementation-open-questions.md
这份文档负责什么
Section titled “这份文档负责什么”只负责记录：
- 还没定死的问题
- 当前存在多个备选方案的问题
- 会影响后续实现，但当前不阻断 Phase 1 的问题
应该收纳的内容
Section titled “应该收纳的内容”例如：
- 某些 admin 交互是否需要更完整版本
- podcast 体系何时独立建模
- topic 是否后续独立出单独实体
- 搜索 Phase 2 如何展开
- 推送个性化什么时候接入
- 更复杂的会员权益如何演化
每个问题建议统一格式
Section titled “每个问题建议统一格式”- 问题描述
- 为什么现在还不定
- 不定会影响什么
- 备选方案 A / B / C
- 当前建议
- 预计在哪个阶段决策
3.3 新建审核与修复记录文档
Section titled “3.3 新建审核与修复记录文档”product/yomiya-implementation-review-log.md
这份文档负责什么
Section titled “这份文档负责什么”只负责保留历史审查与修正痕迹，包括：
- 自查报告
- 致命漏洞清单
- 修复记录
- 第二轮排查
- 运营定义层补充中属于“问题发现”的部分
为什么要单独保留
Section titled “为什么要单独保留”这些内容不是没价值，恰恰相反，它们很有价值：
- 帮助团队理解为什么后来做了某些收缩
- 避免重复踩坑
- 给后续 review 提供上下文
但它们不应该继续污染主规格。
3.4 新建未来阶段规划文档
Section titled “3.4 新建未来阶段规划文档”product/yomiya-implementation-future-phases.md
这份文档负责什么
Section titled “这份文档负责什么”只收纳：
- Phase 2 / 3 / 4 能力
- 延后项
- 增强项
- 后续高级玩法
应该收纳的内容
Section titled “应该收纳的内容”例如：
- 完整搜索能力
- 更复杂推荐系统
- 播放模式增强
- 成就 / 游戏化体系
- Push 精细化策略
- 更复杂的会员与商业化机制
- 高级自动化内容运营能力
未来阶段文档可以完整，但不能反向要求当前 Phase 1 一起实现。
4. 当前已有文档与拆分后文档的角色关系
Section titled “4. 当前已有文档与拆分后文档的角色关系”当前已经新增的 3 份收口文档
Section titled “当前已经新增的 3 份收口文档”yomiya-phase1-execution-spec.mdyomiya-canonical-naming.mdyomiya-phase1-scope-boundary.md
这 3 份文档已经承担了“收口层”的职责。
因此新的角色关系应该是
Section titled “因此新的角色关系应该是”A. 收口层（最高优先级）
Section titled “A. 收口层（最高优先级）”yomiya-phase1-execution-spec.mdyomiya-canonical-naming.mdyomiya-phase1-scope-boundary.md
负责：
- 当前阶段目标
- 当前名词冻结
- 当前范围边界
B. 主规格层
Section titled “B. 主规格层”yomiya-implementation-spec-core.md
负责：
- 当前执行细节
C. 问题与治理层
Section titled “C. 问题与治理层”yomiya-implementation-open-questions.mdyomiya-implementation-review-log.md
负责：
- 未决问题
- 历史问题与修复痕迹
D. 后续阶段层
Section titled “D. 后续阶段层”yomiya-implementation-future-phases.md
负责：
- 后续能力
5. 建议的实际迁移规则
Section titled “5. 建议的实际迁移规则”5.1 从现有 yomiya-implementation-spec.md 中移出的内容
Section titled “5.1 从现有 yomiya-implementation-spec.md 中移出的内容”应移到 review-log 的内容
Section titled “应移到 review-log 的内容”- “深度自查报告”整段
- “致命漏洞修复记录”整段
- “第二轮深度排查”整段
- 所有以“漏洞 / 卡点 / 修复”叙述为主的内容
应移到 open-questions 的内容
Section titled “应移到 open-questions 的内容”- 仍未定死的方案型问题
- 暂时保留多方案并列的问题
- 只记录了建议但尚未正式冻结的部分
应移到 future-phases 的内容
Section titled “应移到 future-phases 的内容”- Phase 2 以后的搜索
- 更复杂推荐与 Push
- 更完整会员演化
- 成就 / 游戏化体系
- 高级播放模式
5.2 应保留在 core 的内容
Section titled “5.2 应保留在 core 的内容”只有下列满足“当前有效”的规则才保留在 core：
- 首页当前版模块定义
- Collection 当前版规则
- 当前生效的数据表与接口设计
- 当前生效的打标与入库规则
- 当前生效的 UI / 内容结构规则
如果一段内容读起来更像：
- “之前发现了一个问题”
- “这里有一个风险，建议这样修”
- “以后可以这么演化”
那就不应该留在 core。
6. 拆分执行顺序建议
Section titled “6. 拆分执行顺序建议”Step 1：冻结收口层优先级
Section titled “Step 1：冻结收口层优先级”先明确：
yomiya-canonical-naming.mdyomiya-phase1-execution-spec.mdyomiya-phase1-scope-boundary.md
这 3 份优先于 implementation 类细节文档。
Step 2：从现有 implementation spec 中抽出 core
Section titled “Step 2：从现有 implementation spec 中抽出 core”生成：
yomiya-implementation-spec-core.md
要求：只保留当前生效规格。
Step 3：把历史审查内容整体迁出
Section titled “Step 3：把历史审查内容整体迁出”生成：
yomiya-implementation-review-log.md
Step 4：把未决问题整体迁出
Section titled “Step 4：把未决问题整体迁出”生成：
yomiya-implementation-open-questions.md
Step 5：把未来阶段整体迁出
Section titled “Step 5：把未来阶段整体迁出”生成：
yomiya-implementation-future-phases.md
Step 6：旧文件处理方式
Section titled “Step 6：旧文件处理方式”旧的 yomiya-implementation-spec.md 不建议立刻删除。
建议改造成：
- 过渡索引文档，说明文档已拆分
- 或归档文档，顶部明确“已拆分，请优先阅读新文档”
这样能避免链接和上下文突然断掉。
7. 拆分之后的阅读优先级
Section titled “7. 拆分之后的阅读优先级”后续任何人进入项目，文档阅读顺序建议固定为：
如果是了解项目方向
Section titled “如果是了解项目方向”yomiya-research.mdyomiya-content-strategy.mdyomiya-phase1-execution-spec.mdyomiya-canonical-naming.mdyomiya-phase1-scope-boundary.md
如果是进入执行
Section titled “如果是进入执行”yomiya-phase1-execution-spec.mdyomiya-canonical-naming.mdyomiya-phase1-scope-boundary.mdyomiya-implementation-spec-core.md
如果是查历史争议和修复原因
Section titled “如果是查历史争议和修复原因”yomiya-implementation-review-log.md
如果是规划下一阶段
Section titled “如果是规划下一阶段”yomiya-implementation-open-questions.mdyomiya-implementation-future-phases.md
8. 这次拆分真正想解决的，不是文档多，而是文档可信度
Section titled “8. 这次拆分真正想解决的，不是文档多，而是文档可信度”项目走到现在，最大风险已经不是“没有想法”，而是：
文档越来越多，但每份文档的职责越来越模糊，最后谁都不敢完全信哪一份。
拆分的真正价值是：
- 让当前有效规格重新变得可信
- 让历史问题有地方放，但不污染执行面
- 让未来阶段有地方规划，但不侵入当前范围
9. 最终原则
Section titled “9. 最终原则”规格文档负责给答案，不负责保留所有讨论过程。
历史记录值得保留，但必须退出主规格。
未来阶段值得规划，但不能反向扩大当前执行范围。
任何一份文档都必须让读者在 3 分钟内知道：它到底是做什么用的。
10. 一句话总括
Section titled “10. 一句话总括”这次拆分的目标，不是把一份大文档拆成很多小文档，而是把“当前有效规格、未决问题、历史修复痕迹、未来阶段规划”四种不同性质的信息彻底分层，让 Yomiya 的文档体系重新恢复可执行性和可信度。