AI辅助技术文档开发:从需求登记,到文档发布 | 技术传播

大家好，我是睿齐。

在介绍 HEXA 的过程中，曾经有一位产品经理提问：HEXA 如何保证 Agent 输出的产品设计的质量？

这是一个 HEXA 如何与具体业务场景结合，保证信息质量的问题。

事实上，HEXA 提供的是一个软件工程管理的框架，借助 Agent 全量维护人机可读的工程信息，一方面帮助团队成员输出项目文件，对齐关键信息；另一方面帮助 Agent 构建上下文，保证执行质量。

但是， HEXA 并没有野心替代每个具体项目成员。每个环节输出的信息质量，需要项目成员自行保证。

在这个实践中，我将作为一个具体的项目团队成员——文档工程师——借助 HEXA 工程管理框架，结合 Sphinx 文档工程流程规范（LEXI），从登记文档需求开始，到文档发布，完成一轮从 0 到 1 的 Sphinx 文档开发，以此为示例，阐述 HEXA 软件工程管理框架，与具体业务场景结合使用的思路和效果。

案例说明

本文以“开发 HEXA 用户指南”为例，完整展示文档需求输入+文档设计（ID）+设计评审（REV）+任务执行（开发/测试/发布/验收）全流程。

在整个过程中 HEXA 和 LEXI 两者各司其职：

HEXA 负责

• 依赖管理（inherit）：继承/管理 LEXI 流程规范；

• 文档管理（document）：管理需求输入；输出文档设计（ID）；记录设计评审（REV）；分析项目信息依赖；

• 任务管理（task）：管理任务执行过程（开发/测试/验收等）；

LEXI 负责

• 说明文档开发规范，包括但不限于语法/文法/术语/工程规范等；

• 提供文档开发相关内容模板、工程模板等；

• 明确具体工作流，如如何进行内容设计（ID）、文档开发、文档测试等。

工程目录架构说明

在开始实践之前，我们先了解一下 HEXA 的工程目录架构，尤其是，与本次文档开发实践直接相关的目录：

第 1 步：前提条件——继承 LEXI 文档技能包

HEXA 的文档管理模块（document）只负责工程管理，并不直接具备文档开发技能，所以我们从继承 Sphinx 文档工程技能（LEXI）开始。

操作过程

在 00/inhert 目录下，通过 subtree 继承 lexicanopy 工程。

关键价值：通过继承，实现 HEXA 工程管理到具体业务场景的灵活拓展。

第 2 步：登记需求——告诉 Agent “做什么”

作为文档工程师或文档团队，我们可能对接各种文档需求。因此，我们通过 00/document/0-人机接口 登记文档需求，便于汇总和跟踪文档需求。

操作过程

1）用户在 Agent 窗口输入：

• 用户需求描述：开发 HEXA 用户指南

• 相关流程规范：00/inherit/lexicanopy

• 前置信息依赖：00/product/2-产品定义

2）Agent 在 00/document/0-人机接口/document：用户需求说明.md 登记文档需求：IN-DM-001

关键价值

• 将模糊的“写一本用户指南”转化为可执行的结构化需求条目；

• 方便后续汇总和跟踪所有文档需求。

第 3 步：Agent 输出文档设计——给出“怎么做”的蓝图

需求登记完成后，Agent 基于用户需求说明（IN）自动生成文档设计方案（ID）。

操作过程

信息输入：IN-DM-001

信息输出：ID-ug-001-概要设计-HEXA用户指南开发.md

文档设计（ID）主要包含以下内容：

关键价值

• AI 辅助文档内容架构设计：Agent 将零散的需求转化为结构化的设计蓝图，用户可在评审阶段直接修改。

• 自动关联前置信息与流程规范：在 HEXA 工程管理目录内自动关联 product 等模块的信息，以及 LEXI 的流程规范，识别信息缺失并确保遵循统一标准。

第 4 步：用户评审——强制门禁保证质量

HEXA 的核心机制之一是人在环路的强制评审门禁，即未评审通过的设计方案不会进入下一阶段。

操作过程

信息输入：ID-ug-001-概要设计-HEXA用户指南开发.md

信息输出：REV-ID-ug-001-评审意见：HEXA用户指南开发.md，全量包含评审反馈（包括用户原话）、沟通过程、关键决策，以及执行状态和执行结果。

经过多轮评审，确保人机达成一致，最终结论写入文档设计（ID）；文档设计和设计文档状态设置为“已评审”。

评审思路

• 身份与场景确认：确认文档定位和目标读者是否准确。

• 逻辑与结构检查：检查文章结构是否清晰，逻辑是否通顺。

• 规范与一致性验证：确保内容符合流程规范，信息与其他模块保持一致。

• 可执行性评估：评估 Agent 是否能根据设计方案准确执行。

设计评审（REV）示例

关键价值

• 人机达成一致：通过评审沟通，让 Agent 理解用户的真实意图，确保执行结果符合预期。

• 强制评审：每轮评审 Agent 都会记录用户原话、分析过程、修改执行，形成完整的评审轨迹。

• 主动判断：Agent 对用户反馈进行合理性判断，并主动识别风险问题。

• 闭环追踪：每条评审意见都有修改追踪记录，确保没有遗漏。

• 可复盘总结：全量记录任务执行过程中的评审意见，便于任务完成后，迭代改进 LEXI 流程规范。

第 5 步：创建执行任务——从设计到实施的转换

评审通过后，HEXA 自动创建执行任务（task），将设计方案转化为可执行的工作项。

操作过程

1）在任务管理目录（task）创建任务执行目录。

2）Agent 读取已评审通过的文档设计（ID）：

• 输出任务定义文档（P0/P1/P2 优先级排序）

• 关联执行依据（工作流、元指令、通用规则）

任务定义示例

• 任务目标：P0 初始化→P1 内容编写→P2 编译验证→人在环路评审验收；

• 现场环境快照：工作区根目录、项目目录路径、当前输入资料；

• 待办清单：按顺序列出每个阶段的具体动作和产物；

• 验收标准：12 项检查清单 + 人在环路评审验收环节；

• 重开 Agent 启动方式：确保上下文可恢复。

关键价值

• 上下文可追溯：所有输入资料、执行依据、验收标准都记录在任务定义中，任何时候重新启动 Agent 都能快速恢复上下文；

• 自动关联规范：Agent 自动关联设计文档涉及的流程规范和模板，确保执行过程的规范性。

第 6 步：文档工程实现——Agent 执行与上下文继承

任务创建后，Agent 按照执行计划分阶段实现文档工程。

执行过程

执行流程示意图：

在任务执行过程中，Agent 自动记录执行过程：

并输出执行报告和测试报告。

执行报告示例

测试报告示例

关键价值

• Agent 执行过程无人值守：Agent 按照执行计划自动完成所有步骤，无需人工实时干预；

• 执行报告便于核对：每个阶段完成后输出执行报告，人类用户可据此抽检验证；

• 人机异步完成：Agent 执行和人类验收可以异步进行，提高协作效率；

• 支持断点续跑：如果任务中断，可从上次执行点继续，无需从头开始。这得益于任务定义和实施日志的完整记录。

第 7 步：交付成果——Sphinx 文档工程

最终交付物是一个完整的 Sphinx 文档工程。

编译结果

• Sphinx 版本：8.1.3

• 主题：sphinx_rtd_theme

• 源文件数：11 个（10 章节 + 1 索引）

• 编译状态：无警告、无错误

第 8 步：验收、信息依赖分析与 LEXI 迭代改进

文档工程开发完成后，进入验收环节。

验收思路

1）检查文档内容是否符合设计方案预期。

2）对不满足规则的地方，分析是什么原因造成的。

3）分析文档的信息依赖关系，确保可根据依赖关系快速定位变更影响的章节；也可自动识别前置信息冲突。具体信息依赖关系说明（ID-DM）参考下方示例。

4）将改进后的流程规范、写作标准等沉淀到 LEXI 技能包中。下次执行时，Agent 会基于迭代后的 LEXI，输出更贴合预期的结果。

文档信息依赖说明示例

关键价值

• LEXI 迭代改进：通过评审→分析→优化→执行的闭环，保证每次执行都在不断完善，逐步逼近预期目标。

• 信息依赖与全局一致性：通过信息依赖关系分析，确保文档内容与其他工程信息保持同步。当来源信息变更时，可快速定位受影响的章节并同步更新。

收获了什么

• 标准化流程：需求登记→设计→评审→任务→执行→交付→验收，每一步都有明确的产物和记录；

• 强制评审门禁：最大限度达成人机一致，确保 Agent 执行效果满足预期；

• 业务层面的质量保证：HEXA 提供框架，但具体的业务规范（章节结构、术语映射、完成度标准）由产品经理/团队定义；

• 信息依赖与全局一致性：直接获取前置工程信息，确保信息依赖关系和全局一致性。通过信息依赖关系分析（见第 8 步），当来源信息变更时可快速定位并同步更新受影响的文档章节。

• 可追溯：每一步的输入、输出、决策都有文件记录，形成完整的开发链路；

• 可恢复：任何时候重新启动 Agent，只需读取任务定义+实施日志即可恢复上下文；

• 可复用：已评审通过的设计方案、已验证的执行步骤可以作为后续项目的参考素材；

• 可迭代：评审记录中的遗留问题、改进建议自动流转到后续迭代中；

• 可拓展：HEXA 本身简洁轻量，但可以在此基础上灵活拓展，对团队协作或人机协作起到辅助支持作用。

HEXA 本身是简洁轻量的，但可以在此基础上，灵活拓展具体业务场景的流程规范。

这次文档开发实践展示了 HEXA 文档管理模块（document），与 LEXI 配合完成从文档需求登记，到文档发布的完整链路。

其关键在于：

HEXA 提供框架，LEXI 定义具体业务场景的流程规范，人在回路强制评审保证质量，迭代改进逼近预期目标。