2026-04-03-yomiya-docs-restructure-design

Yomiya 文档结构重构设计

项目：product/YomiyaContentSystem 目标：在不丢失推理细节和历史证据的前提下，把当前多头分散、重复定义的文档体系重构为“执行层 + 证据层”的双层结构，让开发、产品、iOS、内容运营可以更快进入行动。 范围：只处理 product/YomiyaContentSystem/ 及其在本目录内的文档结构与正文职责，不涉及仓库其他目录。 最后更新：2026-04-03

---

1. 要解决的问题

当前 YomiyaContentSystem 已经积累了大量高价值内容，但存在 4 个直接影响协作效率的问题：

1. 同一件事散落在多份文档里，读者需要交叉跳转
2. “当前现实”“目标规格”“推理过程”“历史争议”混在不同层级，阅读成本高
3. 目录编号只表达阶段，不表达阅读意图，新读者不清楚先看什么
4. 很多长文档有高价值推理过程，但开发和协作方没有时间读完全部内容

本次重构不追求删内容，而是要把内容重新分层：

• 上层压缩出少数直接可执行文档
• 下层完整保留推理、样本、历史、争议和分析过程

---

2. 设计原则

原则 1：不随意丢弃细节

所有已有推理、判断、样本、历史争议默认保留。允许重写主文档，不允许把原始过程直接吞掉。

原则 2：执行层只回答“现在怎么做”

开发、产品、iOS、运营默认只需要看到少数核心文档。执行层不再承载冗长推理过程，只承载当前有效结论、边界、任务和阅读入口。

原则 3：证据层完整保留“为什么”

竞品研究、推导过程、历史 review、旧实现规格、开放问题和未来演化都保留，但不再作为默认入口。

原则 4：编号服务于阅读体验

目录编号必须同时表达优先级和语义，而不是只按历史阶段编号。

原则 5：旧文档允许降级，不允许无痕消失

被合并或替代的旧文档应转移到新的证据层或历史层，并在新文档中给出角色说明。

---

3. 目标目录结构

product/YomiyaContentSystem/
├── README.md
├── 00-Start-Here/
│   ├── README.md
│   └── yomiya-action-plan.md
├── 10-Current-System/
│   ├── README.md
│   └── yomiya-system-source-of-truth.md
├── 20-Execution-Spec/
│   ├── README.md
│   └── yomiya-spec.md
├── 30-Research-and-Evidence/
│   ├── README.md
│   ├── foundations/
│   ├── competitive-analysis/
│   ├── samples/
│   └── mapping-notes/
├── 40-History-and-Decisions/
│   ├── README.md
│   ├── legacy-specs/
│   ├── review-logs/
│   └── split-history/
└── 50-Future-Questions/
    ├── README.md
    ├── future-phases.md
    └── open-questions.md

---

4. 两层结构定义

4.1 执行层

给开发、产品、iOS、内容运营直接使用，只保留以下 4 个默认入口：

1. README.md 仓库内总导航，只负责解释整体结构、阅读路径和权威关系。

2. 00-Start-Here/yomiya-action-plan.md 唯一行动总账。负责回答：

   • 当前 Phase 1 到底做什么
   • 先做什么，后做什么
   • Backend / iOS / Admin / Ops 各自负责什么
   • 默认阅读入口是什么

3. 10-Current-System/yomiya-system-source-of-truth.md 当前系统现实总账。负责回答：

   • 当前正式存在什么对象、字段、关系、约束
   • 当前没有什么
   • 当前理想和现实之间的差距动作

4. 20-Execution-Spec/yomiya-spec.md 当前目标规格总文档。负责回答：

   • 当前目标模型、命名、边界和页面职责
   • 首页 / 列表页 / 合集详情页 / 内容详情页如何工作
   • Phase 1 当前有效冻结表和执行规则

4.2 证据层

给需要追溯推理过程、查看样本、理解历史争议、继续研究和判断未来方向的人使用。

• 30-Research-and-Evidence/ 保留原始研究、竞品判断、样本清单、对象映射说明

• 40-History-and-Decisions/ 保留旧规格、拆分方案、review 记录、历史决策过程

• 50-Future-Questions/ 保留当前未决问题和未来阶段路线

---

5. 现有文档迁移策略

5.1 当前现实层

• 保留并迁移：
  • 02-Current-Execution/yomiya-system-source-of-truth.md
  • 迁移到 10-Current-System/yomiya-system-source-of-truth.md

5.2 当前执行规格层

以下文档不直接删除，而是整合为新的 20-Execution-Spec/yomiya-spec.md：

• 02-Current-Execution/yomiya-phase1-execution-spec.md
• 02-Current-Execution/yomiya-canonical-naming.md
• 02-Current-Execution/yomiya-phase1-scope-boundary.md
• 02-Current-Execution/yomiya-implementation-spec-core.md
• 02-Current-Execution/yomiya-frontend-page-architecture.md

整合后的原则：

• 保留所有当前有效结论
• 折叠重复定义
• 用连续可读的章节结构表达“目标 -> 命名 -> 边界 -> 页面 -> 冻结表 -> 执行规则”
• 原文迁入 40-History-and-Decisions/legacy-specs/

5.3 行动计划层

以下内容上收为 00-Start-Here/yomiya-action-plan.md：

• 02-Current-Execution/yomiya-phase1-delivery-plan.md 中的任务拆解、角色分工、里程碑
• 现有 README 中对“谁先看什么”的阅读路线
• spec 和 source-of-truth 中当前最关键、最需要立即执行的动作

上收原则：

• 行动计划只保留可执行结论
• 每个结论必须指向其所属权威文档
• 详细推理和历史脉络不在行动计划中展开

5.4 研究证据层

迁移到 30-Research-and-Evidence/：

• 01-Foundations/yomiya-research.md
• 01-Foundations/yomiya-content-strategy.md
• 01-Foundations/yomiya-engineering-gap-analysis.md
• 05-Content-Ops-and-Competitive-Research/播客与视频内容统一分析标准.md
• 05-Content-Ops-and-Competitive-Research/播客与视频竞品统一样本清单.md
• 05-Content-Ops-and-Competitive-Research/Mirra播客排查与运用.md

细分建议：

• foundations/ 保留策略蓝图、早期研究、工程差距分析
• competitive-analysis/ 保留 Mirra 这类专项研究正文
• samples/ 保留统一样本清单
• mapping-notes/ 保留统一分析标准和映射方法

5.5 历史与决策层

迁移到 40-History-and-Decisions/：

• 03-History-and-Governance/yomiya-implementation-review-log.md
• 03-History-and-Governance/yomiya-implementation-spec-split-plan.md
• 03-History-and-Governance/yomiya-implementation-spec.md
• 03-History-and-Governance/yomiya-product-ops-review-log.md

5.6 未来问题层

迁移到 50-Future-Questions/：

• 04-Open-Questions-and-Future/yomiya-implementation-open-questions.md
• 04-Open-Questions-and-Future/yomiya-implementation-future-phases.md

---

6. 新主文档应如何写

6.1 README.md

必须做到：

• 一屏内讲清目录结构
• 明确“默认只看哪几份”
• 明确各目录的权威关系
• 给不同角色提供阅读顺序

6.2 00-Start-Here/yomiya-action-plan.md

建议章节：

1. 当前一句话目标
2. 当前默认阅读顺序
3. Phase 1 当前必做项
4. 角色分工
5. 里程碑
6. 默认行动顺序
7. 哪些内容不在当前轮次
8. 细节去哪里查

6.3 20-Execution-Spec/yomiya-spec.md

建议章节：

1. 本文档角色
2. 当前阶段目标
3. 当前命名与对象定义
4. 当前边界与不做项
5. 当前页面体系与职责
6. 首页 / 列表页 / 合集详情页 / 内容详情页规格
7. 内容进入系统的规则
8. 标签与容器规则
9. 标题 / 封面 / 分发规则
10. 当前阶段最小工程方向

6.4 证据层文档

原则是不削细节，只加导读：

• 在文首加“本文件在新体系中的角色”
• 说明它是否还能反向覆盖执行层
• 提供回写路径和关联主文档

---

7. 不丢细节的具体处理规则

1. 不删长文档的推理正文，只改位置、改角色说明
2. 对超长研究文档，允许新增“压缩摘要”段，但全文保留
3. 对被上收的结论，在主文档里尽量保留来源索引
4. 对旧规格文档，不在原地继续演化，统一转历史层
5. 目录迁移后，每个目录必须有自己的 README.md，解释“这一层是干什么的”

---

8. 风险与防呆

风险 1：合并主规格时误删细节

处理方式：

• 先迁移原文，再重写主文档
• 原文全部保留到历史或证据层

风险 2：新的 spec 继续变成第二个巨型总文档

处理方式：

• spec 只收当前有效结论
• 推理过程、样本、历史争议禁止继续堆入 spec

风险 3：行动计划变成第二份规格书

处理方式：

• 行动计划只收“该做什么”
• 规范性定义统一回链到 source-of-truth 或 spec

风险 4：后续又新增平铺目录

处理方式：

• 一级目录固定为 00/10/20/30/40/50
• 新内容只能进入既有层级

---

9. 本次重构的完成标准

满足以下条件，才算完成：

1. 新读者 5 分钟内能知道先看哪 3-4 份文档
2. 开发不必再同时打开 8 份以上文档才能理解当前要做什么
3. 所有旧的高价值推理、样本、争议和历史过程仍然可追溯
4. “当前现实”“当前目标规格”“当前行动计划”“研究证据”“历史与未来”不再混层

---

10. 一句话结论

这次重构不是删文档，而是把 Yomiya 文档体系从“按历史积累自然长出来的堆叠结构”，改成“执行层高压缩、证据层完整保留”的双层可协作结构。