粒度与边界设定
§1摘要与结论
别名：0813 维度6 检索粒度、粒度与边界、模块划分、服务切分、认知负荷边界 | 英文：Granularity and Boundary Setting | 类型：方法 / practice
§2局部关系图
§3原理 · 为什么
分解的判据决定系统的理解成本与变更波及面。若按处理步骤或执行流程切分，一个核心变化会波及几乎所有模块，因为每个步骤都承担共同决策；若围绕「可能变化的设计决策」切分，把易变点封装在少数模块内，则变更被局部化。粒度本身也是一把双刃剑：切得过粗，模块承担多重职责、变更影响大；切得过细，接口与间接层激增、理解一处逻辑需跨越更多单元，产生 classitis 式复杂度，微服务过细同样如此。因此边界应按变更对齐，使模块的粒度匹配真实变化的粒度。边界不仅是技术问题，也是组织问题：康威定律指出系统结构会复制组织沟通结构，模块切分与团队边界应相互配合。最后，人的认知负荷有限，每个新增职责与边界都消耗心智带宽，粒度必须以可理解的复杂度为约束。边界划分还受信息传递成本影响：跨边界的每次调用都带来理解与协调开销，因此边界应尽量落在信息交换最少、语义最内聚的地方。由此，边界设定应同时回答技术切分与责任划分两个问题，二者割裂会持续制造协调成本。把边界当作组织与技术的联合设计对象，并在团队与需求变化时同步复核，才能让结构持续服务于变更而非阻碍变更，避免一次成型后长期失配。
§4机制 · 如何运作
边界设定沿三条线索运作。第一，按信息隐藏分解：识别系统中哪些设计决策最可能变化，把它们作为模块的「秘密」封装，接口只揭示尽量少的内部工作，从而缩小变更影响半径。第二，用耦合与内聚度量校准：内聚刻画模块内部元素是否围绕同一目标，耦合刻画模块间依赖的强度与类型；高内聚低耦合是方向，但无普适阈值，须结合变更频率与领域语义判断。第三，以认知负荷与团队边界约束规模：一个模块或服务应能被一个团队在可承受的认知负荷内理解与维护，并与团队的职责边界同步；当组织调整时，架构边界应被重新审视。三者共同把「切在哪里、切到多细」从直觉判断转为可讨论的结构决策。当模块的划分依据发生变化时，旧的边界会从资产变为阻力，因此需要把边界视为可重构的假设，而不是一次成型的结构。
§5工程 · 怎么落地
落地时先用变更场景驱动分解：列出未来最可能发生的修改，推演它会影响哪些模块、需要触碰多少文件、是否存在循环依赖或跨层直连，据此调整边界使变化局部化。把易变的决策收进单一模块并隐藏其实现，把稳定的契约固化为接口。对服务切分，以业务能力或限界上下文对齐，避免按技术层切分导致跨服务的高频耦合。用耦合内聚度量作为巡诊信号定位可能承受连带修改的模块，但不以阈值自动判定。切分后以真实变更验证：下一次同类修改是否只触动预期范围。让模块边界与团队边界同步演化，交接清晰的模块配自主负责的团队。对新增的间接层设退出条件，当它不再带来可修改性收益时拆除，防止粒度碎片化累积。用依赖结构矩阵或调用图可视化跨边界关系，能直观暴露本应隔离却相互纠缠的部分，辅助再切分。
§6权衡卡
边界与粒度决策代价明确。
切分过粗使变更牵动大片、职责混杂；切分过细则接口膨胀、跳转增多、理解成本上升，并可能引入分布式系统的额外代价。
因此应以真实变更模式为判据，在局部化收益与拆分成本之间取舍，并让边界随变化与组织同步调整，而非一次切死。
- 此外，耦合内聚无普适阈值，机械套用某度量值会误判。
- 还要避免把粒度当成可孤立优化的目标：模块边界同时受技术、组织与认知三重约束，仅按其中一维调整往往会破坏另外两维的平衡。
权衡原文仅按显式标记词归栏引用（收益 / 代价 / 反例），其余句子按原序列为「原文要点」；内容逐字引用未改写。
§7案例带
dsh-manager 插件深度分析
以「编译依赖、运行时注入、组合装配」三硬依据加源码行号，对第三方插件做依赖、功能、需求溯源与设计问题裁决，并复用上游 DAG 知识库节点标识，使分析结果可与主图互查。
dsh 插件依赖增量定位
以官方插件 DAG 为蓝本，对一个官方清单之外的全新社区插件做功能定位与依赖位置增量分析，产出可下钻交互依赖图与多形态文档的源码级架构逆向案例。
AI Agent 架构 DAG 复盘
对四个工作日内独立完成三个异构对象 DAG 分析的方法论复盘，总结「采集→建模→生成→门控→交付」可复用管线与关键教训。
去中心化聊天架构逆向
对一个仅有 58 份设计文档、尚未实现的开源去中心化聊天项目做架构逆向：从设计文本提炼 18 个模块及其依赖关系，重建模块依赖 DAG 与三条核心数据流 DAG，并输出全景理解与深度需求分析。
网申填写扩展逆向架构
对 Chrome MV3 网申自动填写扩展的逆向架构分析：梳理 popup、content、background、options 四模块职责，解剖 12 个站点适配器、双通道消息协议与隐私脱敏机制，并评估其零依赖零构建选型。
网申 v3 多模块解耦
一套面向高可扩展性的网申信息速查扩展架构：以 schema.js 为唯一数据驱动源，把数据模型、存储、纯函数与渲染组织为严格单向依赖的共享层，供 popup 与页面浮层双容器复用，并先立跨模块接口契约。
网申 v2 深度重构
一次由「改一处漏多处」症状触发的深度重构：定位到接口定义散落 12 个文件、存在 7 种接口形态的根因后，以单一契约源、dispatch 消息表与能力注册中心重建三层契约系统，恢复可审计与可校验性。
preset 通道耦合分析
对 harness「委派工具层→续用管理器→preset 服务→MCP 服务器」这条通道做耦合分析：识别契约、服务定位、数据契约、组合语义、路径与装配一致性六类耦合点，定位「静默丢弃特化」与「装配漂移」两处实质缝隙。
插件 DAG RC5→RC7 升级
一次知识库随上游源码版本升级的级联维护：以三层差异分析把 219 个包收敛为 26 个实质变更包，经编译、运行时、组合三类依赖判定更新 DAG 数据后全量重生成页面，并以静态门控加渲染验证收口。
harness 源码架构解析
对 deepseek-harness 官方源码做分层解析：镜像官方架构文档，按九个层与九十余模块建立文档集群，产出跨层联动矩阵与七条关键路径，并钉住「模型可见即已记录」、能力缝三角等设计不变量。
MCP 四件套选型对比
对四个同类 MCP 服务器做源码级能力与成本对比，并以常驻 token 预算为轴给出分级接入策略的技术选型实战案例。
Claude Code 架构逆向
以社区逆向源码、系统提示词与官方文档三源交叉验证，还原一个商业 Agent 的查询引擎、子Agent、工具与权限体系的逆向分析案例。
Open Code Review 图谱
对阿里开源 AI 代码审查 CLI 做源码级解析并构建「知识 + 实践资产 + AI 索引」三合一知识图谱的工程案例。
控制理论⊗Agent 设计
将控制理论五维（负反馈 / 状态估计 / PID / 鲁棒 / 分层）系统映射到 Agent 工程环节，并以真实产品案例验证的跨学科方法论案例。
技术知识中枢交付法
从模糊需求到上线，把 AI Agent 驱动的端到端交付固化为四阶段加双共识加迭代的可迁移方法论的实战提炼案例。
§8信源与核验
核验结论：粒度存在双向代价：过粗使变更波及面大，过细则接口与间接层激增、认知成本上升；应按变化点对齐切分，并以认知负荷约束规模 [BK-008]
§9原始关系清单
展开：本节点的全部原始关系边（5 条，含边 ID 与方向）
| 关系 | 方向 | 对端节点 | 说明 |
|---|---|---|---|
| 案例印证 | ← CAS-X-08 | dsh-manager 插件深度分析 E-961 | 张力：双单体大文件反映边界粒度过粗，难独立变更 |
| 案例印证 | ← CAS-X-10 | dsh 插件依赖增量定位 E-971 | 张力：受蓝本粒度约束，增量定位精度受限 |
| 案例印证 | ← CAS-X-18 | AI Agent 架构 DAG 复盘 E-995 | 印证：组级视图加下钻的粒度控制 |
| 依赖关联 | ← MTH-O-05 | 质量属性冲突治理 E-702 | 属性冲突治理需在粒度边界上落地 |
| 依据推导 | → ESS-O-01 | 本质复杂度与偶然复杂度 E-688 | 粒度决定偶然复杂度与理解成本 |
附对照资源 · 12factor 子库
| 12factor 节点 | 关系 | 对照说明 |
|---|---|---|
| 并发 app-concurrency | 跨体系对照 | 以进程模型横向扩展对应可演化/可扩展性与粒度边界设定方法 |
| 工具即结构化输出 ag-tools | 跨体系对照 | 工具即可组合单元，对应模块化分解与粒度/边界设定 |
| 小而专注的 Agent ag-small | 跨体系对照 | 小而专注的 Agent 对应模块化分解与细粒度单元边界 |
| 规模化与单元粒度 t-scaling | 跨体系对照 | 进程模型扩展与小 Agent 组合皆单元化扩展，对应可扩展性与粒度设定 |