前阵子参加一个项目的文档评审会看到对面一位同事翻着三百多页的软件设计说明问开发组长“这个模块在代码里都重构过两轮了为什么设计文档还停留在三个月前的状态”组长的回答很直接“一直在赶功能文档是评审前补的。”这个场景我太熟悉了。GJB438B时代我们就在讨论“文档与代码同步”到了GJB438C-2021发布后这种“先写代码、后补文档”的做法其实越来越行不通了——不是因为标准管得更严而是因为新规把文档重新放回了工程过程里。今天我想抛开标准条款的罗列从一个做软件研制的工程师视角聊聊GJB438C-2021新规下文档该怎么写、怎么写才能不为写而写以及我在实际项目里踩过的坑和试出来的做法。这篇文章不面向标准专家面向的是那些和我一样被文档压得喘不过气、又知道文档确实不能丢的一线开发和软工人员。1. GJB438C-2021到底改变了什么不只是换版而是把文档放回工程过程里1.1 从“模板合规”到“数据与过程一致”C版最核心的思路转向先说一个很多人没意识到的背景。GJB438C-2021不是独立存在的它是和GJB2786A《军用软件开发通用要求》、GJB5000B《军用软件研制能力成熟度模型》配套使用的。换句话说C版调整的不只是文档的格式和章节而是文档在整个研制流程中的定位——文档不能只是“交差用的纸”它必须反映真实的工程过程数据。B版时代一个常见的操作是立项后先不写文档等代码写差不多了照着代码“还原”一份需求规格说明和设计说明。评审前突击补文档甚至成了很多团队的标准流程。这种做法在C版框架下会带来连锁问题C版强调文档之间的一致性、需求的可追踪性、设计与代码的对应关系。你补出来的文档往往在表面格式上没问题但在“数据层面”漏洞百出——需求条目和测试用例对不上设计描述和模块接口对不上计划文档里的进度和实际里程碑对不上。我在实践中体会最深的是438C-2021把“文档评审”更多转向了“数据检查”。评审专家不再只看你有没有按照模板写全章节而是直接抽取两条需求从需求规格说明追到设计说明、再追到测试用例、最后追到测试报告里的结果。追不上文档写得再漂亮也要打回。所以在C版逻辑下文档的真正作用只有一个把研制过程中的信息连续地、无歧义地传递下去。1.2 裁剪机制被真正激活但很多人不会用438C-2021对文档裁剪的规定比B版更灵活这是好事但也是很多团队的坑。我在一些合作单位看到他们把“裁剪”理解为“少写几份文档”甚至直接把软件测试计划、软件配置管理计划这些勉强算“非核心”的文档裁掉结果到了第三方评审时被连续驳回。裁剪的目的是什么是让文档集的规模和项目的规模、安全性级别、关键等级匹配。它不是让你少干活而是让你把有限的精力投到最该写清楚的内容上。C版允许裁剪的前提是你要在项目启动阶段做裁剪分析说明为什么某份文档里的某一章或者某一节不适用并且保留裁剪记录。举个例子一个只做算法验证的软件项目没有复杂的人机交互界面那么“软件用户手册”里关于界面操作的章节确实可以裁掉但你得在裁剪说明里写清楚依据而且“运行环境”“安装与卸载”这些涉及部署的内容哪怕再简单也建议保留。反过来一个飞行控制软件哪怕规模不大需求追踪矩阵、接口设计这些内容一个都不能省因为这直接关系安全。我自己在做裁剪分析时有一个原则只裁“形式”不裁“信息”。也就是说如果某份文档的某一章对当前项目没有信息增量那可以合并或删减格式但如果这个信息在研制过程里仍然存在需求比如某个限制条件、某个接口约定那它就必须出现在某一处文档里。2. 告别“为了写而写”的根子我对三个典型病根的诊断2.1 病根一文档晚于开发设计说明成了“考古报告”这是最普遍的问题。文档一旦晚于开发它就不是在设计而是在描述历史。我自己写过这种文档那种感觉非常难受——你要去读代码、猜当时的意图、甚至去问已经调走的同事“这个函数为什么这么设计”问到的答案往往是“当时这么写能跑通过”。代码和文档之间天然存在“时差”这是正常的C版不是要求消灭时差而是要求不能让时差大到文档失去参考价值。我在目前带的项目里强推了一个简单规则代码合入主干之前相关设计说明必须更新到对应版本。听起来简单但执行起来需要配套手段后面我会细说。没有这个规则设计说明就一定变成考古报告而且是那种带着推测和模糊记忆的考古报告对后续维护没有任何帮助。2.2 病根二把评审当终点文档没进入项目回路GJB438C-2021里反复出现的一个词是“基线”。软件需求规格说明通过评审后就要建立需求基线设计说明通过评审后设计基线测试完成并报告通过评审后产品基线。很多团队把“通过评审”当成任务完成的标志文档就再不碰了。但基线不是终点是起点。基线意味着这个时点的状态被固化后续任何变更都要经过正式的变更控制流程。如果评审一过需求基线就锁死了而开发过程中需求调整、设计调整不停发生那么基线和实际状态就会越来越远。到了软件维护阶段文档已经完全不能信任了。在C版的项目里我越来越认同一个说法文档是一个信息基础设施它的价值是在变更中体现的。一份从不更新的文档即使内容全对价值也随时间持续衰减一份在变更中持续更新的文档才是项目真正的资产。2.3 病根三需求追踪矩阵沦为“花名册”需求追踪矩阵是GJB438系列中几乎贯穿所有文档的工具从需求规格说明到测试报告都要引用。但我见过太多需求追踪矩阵只是把需求编号、设计条款、测试用例编号罗列在一起看起来工整实际没有任何工程作用。真正的需求追踪矩阵是用来回答问题的这条需求为什么存在它在设计里落到哪个模块测试靠哪条用例证明它被实现了某个设计变更会影响到哪些需求如果没有一个可以逐条回答这些问题的追踪矩阵文档里那一排表格就是摆设评审专家一追就会露馅。我后面会讲怎么做一个“能用”的需求追踪矩阵这里先指出一个观点需求追踪矩阵没有技术含量它考验的是工程习惯。你能不能做到每次需求变更、每次设计调整、每次测试补充时同步维护它决定了这个表格是资产还是垃圾。3. 让文档产生价值我在新规下的落地实践3.1 需求追踪矩阵帮助开发“找路”而不是“交差”先说追踪矩阵因为它是GJB438C-2021文档体系的枢纽。我用的方法不复杂主要是一个原则加一套状态管理。原则是每条需求必须是一个独立的、可验证的条目。C版对需求条目化的要求比B版更细不能再把“系统应能在各种恶劣气象条件下正常工作且性能指标满足要求并具有良好的可维护性”这种一句话包含三个意思当一条需求。拆分后每条需求要有唯一编号、来源通常是软件研制任务书/系统需求、描述、优先级、验证方法分析/演示/测试/检查和当前状态。状态管理上我在表格里加了四列设计位置、代码模块、测试用例、验证状态。每一列不是写一次就完了而是跟着项目走。需求有变更可以在表格旁边加一列“变更记录”写下变更日期、原因、影响范围。开发过程中每周花十分钟对照一下代码合并记录和追踪矩阵看有没有需求对应的模块改了但状态没更新。这十分钟花得值不值等评审专家抽查的时候你就知道值不值了。3.2 软件设计说明写成可以“照着敲代码”的文档GJB438C-2021把设计说明的重点进一步往“模块设计”“接口设计”“数据设计”上放。很多人的设计说明写得最大而无当的部分是“系统总体架构”——画了一个四层架构图写了一堆“本系统采用分层架构具有高内聚低耦合的特点”这种正确的废话但对每个模块的输入输出、错误处理、状态迁移、关键算法却没有描述到可实现的粒度。我自己把软件设计说明当成“代码的施工图”来写。描述一个模块时至少覆盖四个问题这个模块对外有哪些接口每个接口的输入输出、返回值、异常处理是什么模块内部有哪些主要数据结构关键流程和状态是怎么流转的如果有复杂算法伪代码级别到不了但至少要把思路说清楚。你可能会说这和工作量非常大。确实大但比起“代码写完再补设计”其实省时间因为设计写清楚了开发阶段的反工反而更少。而且C版时代我强烈建议设计说明和代码走同一个版本管理和评审流转体系。我在项目里用的方案是设计说明里的每个模块对应一个Markdown文件存在仓库的docs/design/modules目录下和代码一样参与评审、变更、合并。这样“设计跟着代码走”就不是口号而是操作流程的一部分。3.3 测试文档让测试可复现而不是“补记录”GJB438C-2021对测试文档的要求一个容易被忽略的点是“可复现性”。B版时代很多测试说明里只写“输入一组测试数据检查输出是否正确”但这一组测试数据具体是什么用什么工具、什么环境、什么步骤生成的全都没写。这样的测试文档就是“补记录”因为换一个人来根本没法重复同样的测试。正确做法是测试说明里的每个用例都必须包含前置条件、测试步骤、输入数据或数据生成方法、预期结果、判定准则。不要写“数据合理”这种含糊的表述要写清楚“数据取值范围0到10000步进100每种取值重复3次记录最大值、最小值、均值”。最好把测试脚本或测试配置文件也纳入配置管理和测试说明一同入库。我特别想提的一点是C版更强调测试对需求的覆盖性验证。评审专家会看某条安全关键需求你说验证方法是“测试”那对应的测试用例真的测到了这条需求里所有可验证的内容吗很多团队在这里会栽跟头因为他们的追踪矩阵里“测试用例”和“需求”的关系是随便填的一对多、多对一都没有解释。我的方法是在每条需求的追踪信息里写明具体覆盖了哪几个测试用例并在每个测试用例里写清反向引用它验证的需求编号。双向链接乱不起来。3.4 文档与代码同步版本基线怎么管讲到同步必须说配置管理。GJB438C-2021和GJB2786A、GJB5000B一样都把配置管理当成软件工程化的基础文档的版本管理更是配置管理的一部分。我推荐一个非常务实的做法文档和代码放在同一个配置管理库用同一个版本控制体系。不要文档放在SVN的独立目录、代码放在Git的另一个仓库那样同步只能靠人工记忆。把docs目录放进代码仓文档变更跟着代码提交走代码Merge Request可以同时修改对应文档CI检查里加一个“如果模块代码有变更但对应设计文档没更新流水线直接报警”的规则。这套机制在技术实现上不难难的是要求团队接受“不更新文档就不让合入”的文化。文档的里程碑基线怎么打我的习惯是每一个外部评审节点需求评审、设计评审、测试评审、验收前打一个干净的基线标签和当时的代码标签对应。这个基线的用途不是锁死而是作为后续变更对比的起点。项目结束后归档的时候你能直接拉出任意一个评审节点的完整文档代码快照这种价值在维护阶段会成倍放大。4. 在敏捷迭代下应用GJB438C我的裁剪与适配经验4.1 迭代开发时什么时候写什么文档很多团队一提到GJB就觉得和敏捷是死对头其实不然。GJB438C-2021本身并不强制你用什么开发流程它要求的是文档与过程一致。敏捷开发要适配GJB文档体系关键不是把文档挤到迭代末尾集中补而是把文档工作拆碎分布到每个迭代里。我做过的可行方案是项目启动阶段正常编写软件研制任务书、软件开发计划、软件配置管理计划、软件质量保证计划这些不依赖需求细节可以在早期一次性完成第一个迭代前完成软件需求规格说明的初版并且建立需求基线之后每个迭代做三件事——更新需求规格说明如果有需求变更、编写和更新当前迭代涉及的模块设计说明、编写和更新当前迭代完成的测试说明与测试报告按迭代增量。这样每个迭代结束时文档和代码在“当前迭代范围内”都是同步的评审时不需要临时补几十页文档。很多人担心频繁更新文档太耗时。我的体会是设计说明按模块拆分后每次迭代一般只需要改两个模块的Markdown文件最多半天工作量远比评审前花一周补文档划算。4.2 文档颗粒度控制宁可短但要准适配GJB438C时最容易走极端。一种是一刀切按模板全量输出连“适用范围”都写成模板原话一种是追求“短小精悍”结果把接口定义、异常处理这些关键信息都裁没了。我的颗粒度经验有三个参考标准。第一能指导编码的设计才是合格的——如果开发人员拿到设计说明仍然需要反复找架构师确认接口说明这个模块的设计粒度不够。第二能定位问题的追踪才算有效——需求追踪矩阵里的每一条都应该能从一个需求点击到设计和测试如果点击链断了说明矩阵失效了。第三能支撑复现的测试才值得入库——测试用例是否记录了输入数据、环境配置和操作步骤是测试文档能否支撑回归验证的关键。在这三个标准下文档的篇幅自然会收敛。真正需要写清楚的信息写足废话自然就没地方放了。4.3 自动化工具链把文档操作变成工程习惯关于工具链我推荐组合是Markdown编写、Git版本管理、GitLab或Gitea做评审流转、Jenkins或GitHub Actions做检查。Markdown的好处是纯文本、易diff、评审时能清楚看到改了什么Git的好处是天然支持文档和代码同仓CI可以跑一些简单检查——比如追踪矩阵里的需求编号是否都有对应测试用例编号文档里的接口名是否和代码里的定义一致只要不是纯自然语言描述的内容都可以做成自动化检查项。这套工具链本身不复杂它真正的价值是让“写文档”变成了开发流程里自然的一环而不是评审前的额外负担。你提交代码时发现CI提示“接口文档未同步”顺手就去改了这比事后专门安排一天“补文档”要高效得多。5. 实操中遇到的坑评审、配置管理、外包管控5.1 评审专家最常提的问题提前自查跟第三方评审打多了交道你会发现专家翻来覆去问的问题其实就那么几类。提前自查能省大量来回的时间。常见问题里出现频率最高的包括需求规格说明里的功能需求和非功能需求没有区分性能指标无可验证的量化描述比如“响应时间尽量快”这种需求追踪矩阵覆盖率不足某条需求在测试报告里找不到对应的验证结论设计说明和需求之间不一致设计里的模块需求里根本找不着测试报告中的测试结果只有“通过”二字没有实际测试数据和环境信息文档之间的版本不一致——需求基线的版本、设计文档引用的需求版本、测试报告的版本各说各话。前四个问题靠后文的方法基本都能解决第五个问题有点特殊纯粹是版本管理习惯。我的建议是每份文档开头加一个“引用文档清单”列出它引用的其他文档的名称、编号、版本评审和追溯时这个清单就是全局定位的索引。5.2 文档清单与配置管理最容易在入所时翻车项目收尾阶段软件配置管理的一项关键任务是“文档齐套性检查”。GJB438C-2021调整了一些文档的名称和编制时机新接触的人很容易在文档清单上出错。我踩过的一个坑是项目实施过程中因为裁剪减少了某些文档但交付清单里没有体现裁剪记录导致甲方按全套文档清单核对时查不到对应的文件。后来我养成一个习惯项目开始的第一周就做“项目文档裁剪表”——每一份GJB438C里列出的文档都标注“编制/裁剪/合并”写清裁剪或合并的理由和依据随项目计划一起提交确认。这样文档在交付时清单就是确定的不会再临时补裁剪说明。5.3 对外包/外协单位的文档管控要颗粒度而不是要搬运工最后一个容易被轻视的环节是外包和外协。很多单位的软件研制部分环节外包这就要求在软件研制任务书或外包技术协议里把文档要求写到位。我见过最典型的问题是外包方交付的文档是按他们自己的格式核心信息严重缺失甚至连接口定义都不完整甲方拿来根本没法验收。我的经验是外包技术协议里除了写清楚功能、性能、进度之外还要明确规定文档的种类、版本、格式和交付里程碑。可以以GJB438C的文档为基准加上项目裁剪表做成一个“文档交付计划”作为协议附件。外包方在里程碑节点交付代码的同时必须交付对应版本的文档配置管理库也要同步共享。否则到了集成阶段你去问外包方“这个接口的参数范围是什么”他可能早就离职了只留下一串没有注释的代码。最后说一点我的真实体会从GJB438B到GJB438C-2021我最大的感受不是标准变严了而是标准在逼着软件团队“诚实”——诚实对待过程数据诚实对待文档与代码的关系诚实对待追踪矩阵的每个箭头。文档不是给评审专家表演用的它是项目在时间轴上留下的工程记忆。我自己在带新人时会说你写的每份文档都有可能在你离开项目很久之后被翻出来那时候它能不能让一个完全不认识你的人理解当时的决策和实现才是它真正的价值所在。这也是GJB438C-2021想让我们做到的事情——让软件文档从“为了写而写”变成项目真正用得上的资产。这套方法实践下来前期确实比“先写代码再补文档”多花一点时间但中后期省下来的返工和沟通成本远超那点投入。