文档组织——结构、逻辑、内容槽位与逐项审查

一句话

结构管「放什么、放哪里」，逻辑管「为什么、怎么连」，具体管「里面到底写什么」，审查管「分别有没有问题」。

无论是写文档、文章，还是分析复杂问题，都可以避免一上来就陷入细节。

一、结构与逻辑的区分

结构 = 总和分、上下层次、组成关系

整体由什么组成
每部分属于哪里
哪些是总体、子系统、模块、组件

例如：系统 → 服务 → 模块 → 类 → 函数

逻辑 = 前因后果、条件关系、推导关系、执行关系

为什么产生什么
什么条件下做什么
做了 A 之后导致 B，B 又作为 C 的前提

例如：输入 → 解析 → 判断 → 分发 → 执行 → 输出

「不是东一榔头西一榔头」，正是逻辑性的核心。

结构回答「东西怎么组织」，逻辑回答「事情怎么发生」。

以服务器为例

结构（服务器由哪些东西组成）：

Server
├── Network
├── Protocol
├── Router
├── Service
├── Domain
└── Infrastructure

逻辑（请求怎么一步步变成结果）：

1 2	客户端请求 → 网络接收 → 协议解析 → 路由匹配 → Handler → Service → Domain/Algorithm → 返回结果

工程设计 = 结构 × 逻辑

结构确定「谁负责什么」，逻辑确定「谁先做什么、为什么做、做完产生什么」。

「系统用结构描述，工程用流程描述」是同一组关系：系统偏向回答「它是什么、由什么组成」；工程过程偏向回答「它怎么被构造、怎么运行、怎么验证」。

二、文档的四层组织与内容槽位

结构和逻辑解决「不要乱」，还差「具体放什么」。任何文档/文章的组织可以理解成四层：

结构：放在哪里
逻辑：为什么按这个顺序
内容：具体放什么
表达：具体怎么写

其中最关键的是内容的固定槽位。

最基本的内容骨架

一份比较完整的文档，通常按这个顺序组织（每个位置有自己的职责）：

① 背景       为什么要讨论/做这个东西？
② 目标       最终要得到什么？
③ 范围       做什么？不做什么？
④ 对象       涉及哪些东西？
⑤ 结构       这些东西怎么组成、怎么分类？
⑥ 原理       它们之间为什么这样组织？
⑦ 流程       事情按照什么顺序发生？
⑧ 规则       什么情况下必须怎样？
⑨ 实现       具体怎么做？
⑩ 验证       怎么知道做对了？
⑪ 结果       最终得到什么？
⑫ 限制/问题  目前哪里还不确定？
⑬ 后续       下一步做什么？

这就已经不是「想到什么写什么」，而是每个位置有自己的职责。

以 CLI 程序设计为例

结构（分类）：

CLI
├── 输入（命令 / 参数 / 配置）
├── 处理（Parser / Handler / Service）
└── 输出（Result / Error / ExitCode）

逻辑（因果/过程）：

1 2	用户输入命令 → 解析参数 → 检查参数合法 → 构造请求 → 调用 Service → 得到结果 → 转换为 CLI 输出 → 返回 ExitCode

具体内容（槽位）：

Parser：   输入 argv → 输出 Command
Handler：  输入 Command → 输出 Result
Service：  输入业务请求 → 输出业务结果
ExitCode： 0=成功  1=参数错误  2=执行失败

写东西就是「填槽位」

1 2	主题 → 确定范围 → 建立结构 → 建立逻辑 → 确定每个位置需要回答的问题 → 填入事实/规则/过程/示例 → 检查是否完整

例如一个叫「Parser」的章节，固定回答：Parser 是什么？为什么需要它？输入是什么？输出是什么？处理什么、不处理什么？处理流程是什么？错误怎么处理？怎么测试？——这样写出来就很难乱。

文章 vs 工程文档的区别

文章最核心的是论证逻辑：观点 → 理由 → 解释 → 证据/例子 → 结论
工程文档最核心的是信息完整性 + 可查找性 + 可执行性：对象 → 定义 → 结构 → 接口 → 规则 → 流程 → 实现 → 验证

「该写什么」= 信息单元应该回答什么问题

内容类型	回答的问题
定义	它是什么？
背景	为什么有它？
目标	想得到什么？
范围	管什么、不管什么？
结构	由什么组成？
关系	谁和谁有什么关系？
原理	为什么这样？
流程	先做什么、后做什么？
规则	什么情况下必须怎样？
接口	怎么与它交互？
实现	具体怎么做？
示例	实际是什么样？
验证	怎么证明正确？
限制	哪里不能保证？
结论	最终得出了什么？

真正成熟的写作不是「会写漂亮的句子」，而是：先建立信息结构 → 再建立信息之间的逻辑 → 再确定每个节点应该回答的问题 → 最后填入具体内容。

结构解决「杂」，逻辑解决「乱」，内容槽位解决「空」。

三、审查的拆分：一次只审查一种东西

核心原则：

不是「审查代码」，而是把「代码正确性」拆成很多种互相独立的审查任务，每次只检查一种性质。

每轮只有一个判断问题，输入、检查对象、规则、输出都可以固定。

代码审查八类

① 结构审查——东西放得对不对：分层审查（文件夹是否对应层、是否跨层直接调用、是否反向依赖）、文件归属

② 模块审查——同一功能是否聚在一起：文件是否属于正确功能模块、一个模块是否混入其他功能、是否出现「万能模块」「common.cpp」什么都往里塞

③ 职责审查——它有没有偷偷负责别的事：algorithm/FindProcess() 不应该出现打开文件、创建窗口、打印 CLI、解析命令行、访问数据库

④ 接口职责审查——接口是否只有接口：有没有实现代码、接口是否过大、一个接口是否承担多个不同职责

⑤ 原子化审查——该拆的有没有拆：有没有应该拆而没拆？有没有原子能力还没形成接口就直接开始组合？原则：先形成原子能力，再进行组合

⑥ 组装层审查——拆好的东西有没有正确组合：CLI 是否只负责解析/分发/调用 Service、是否把业务逻辑写进 CLI、是否绕过 Service 直接调用底层组件

⑦ 逻辑审查——事情是否按正确逻辑发生：顺序是否正确、前置条件有没有检查、有没有漏步骤/重复步骤、错误是否正确传播、状态变化是否正确

⑧ 行为审查——功能是否正确、边界是否正确、异常是否正确、测试是否覆盖

文档审查的九项流水线

① 结构审查——有没有放对地方：只信息组织位置，不判断内容对错
② 内容完整性审查——该写的有没有写：逐项打勾，找出缺失项
③ 逻辑审查——是不是东一榔头西一榔头：前后关系（为什么→因此、输入→处理→输出、问题→原因→解决方案）
④ 概念审查——有没有混概念：同一个词是否始终表示同一个东西
⑤ 层次审查——抽象层级有没有混乱：标题是「系统架构」，却突然出现「std::vector 扩容时会重新分配内存」
⑥ 关系审查——该建立的关系有没有建立：A 和 B 是什么关系？是否存在孤立概念？
⑦ 事实审查——说的东西有没有依据：有没有把推测写成事实、把个例写成普遍规律
⑧ 推理审查——结论是不是从前面推出来的：「A 项目成功 → 所以这种架构一定适合所有项目」
⑨ 表达审查——有没有把确定的东西说清楚：歧义、啰嗦、重复、术语统一（表达审查应该比较靠后）

五个基础审查器

结构审查    解决「有没有乱放」
逻辑审查    解决「有没有乱串」
完整性审查  解决「有没有缺东西」
概念审查    解决「有没有说混」
事实/推理审查 解决「有没有说错」

对 Agent 的执行方式

不要给 Agent「全面审查这个项目」，而是分轮给单一判断：

「只检查分层和依赖方向，不检查功能正确性。」
「只检查模块边界，不检查分层。」
「只检查算法文件是否包含非算法职责。」
「只检查 CLI 是否违反 解析→分发→Service调用 这一职责。」

这样就从「凭经验审代码」变成了真正的工程审查流程。

四、闭环与总结

完整闭环

1 2	主题 → 结构：有哪些部分 → 逻辑：部分之间如何关联 → 具体：每个部分写什么 → 审查：逐项检查有没有问题 → 修正 → 再次审查

核心方法：

先建立结构，再建立逻辑；具体内容填入结构；最后把审查拆成一个个独立维度逐项检查。

审查本身也要有结构和逻辑

审查也不能混乱——一次只问一个问题：结构是否合理？内容是否完整？层次是否混乱？概念是否统一？关系是否表达清楚？逻辑是否连贯？推理是否成立？事实是否正确？表达是否清楚？

连审查本身也要有结构和逻辑。

四句话总结

结构管「放什么、放哪里」。
逻辑管「为什么、怎么连」。
具体管「里面到底写什么」。
审查管「分别有没有问题」。

与其他线的关系

与单一职责主题：结构审查、职责审查是单一职责在审查环节的执行——一次只审查一种性质，就是审查的单一职责
与拆解与组织主题：结构 = 拆解的结果，逻辑 = 组织的关系；文档组织是拆解与组织原则在文档上的应用
与设计表示线：设计表示提供八种视图（层级树/流程图/依赖图/时序图/状态图）；文档组织确定这些视图按什么顺序放进文档
与建模与逆向主题：文档的内容槽位就是「模型 → 文章」的展开模板；文档审查就是逆向应用（用模型检查产物）