software

DAT as Code：使用 AI 自动化技术文档

发布: (2025年12月15日 GMT+8 16:39)
6 min read
原文: Dev.to

Source: Dev.to

Introduction

去年，我写了一篇关于现代化 DAT（技术架构文档） 的指南。一年后，随着编码助手及其连接器的出现，我开始思考：我们到底能用 AI 做些什么来维护 DAT？

我在一个 Infra‑as‑code 项目上进行测试。
目标：从零开始，尽可能少的工作量就生成完整的文档（架构 + 运营）。
剧透：只需几小时的设置，就能跑通。

发现：templates + prompts

第一次使用编码助手的测试：我给它一个带有结构（标题、章节）的 markdown 文件，并在 HTML 注释中加入指令。

示例：

## 🏗️ Prérequis

## Description de la gestion IAM

编码助手会遵循结构并根据指令填充每个章节。
看似简单，却是我迄今为止测试过的保持文档风格统一最有效的方法。

问题：需要同步的 3 种工具

在普通项目中，我要在以下工具之间切换：

  • GitHub（代码）：markdown 形式的 doc‑as‑code
  • Confluence（文档）：用于搜索和阅读便利
  • Jira（工单）：用于追踪 issue 和项目

手动维护 Confluence 文档简直是噩梦。
我们希望能够在代码旁的 GitHub 中编写文档，但那样搜索不够方便。
理想状态是：用代码写文档，同时自动同步更新 Confluence，并在其中加入指向 GitHub 文档的链接和引用。

Diagramme GitHub‑Confluence‑Jira

解决方案：MCP（Model Context Protocol）

MCP 是一类连接器，能够让你的编码助手与外部服务对话。我在本项目中确定了三个关键的 MCP：

  • Context7：检查文档是否符合标准并发现缺失内容。
  • GitHub：读取代码（我这里使用 Terraform）以提取架构信息。
  • Atlassian：与 Confluence 和 Jira 交互。

IDE coding assistant + MCP

Setup

我在 IDE（我使用的是 VsCode，其他如 Cursor、IntelliJ 也可）中安装了这 3 个 MCP。
对于 Atlassian，还需要在 .vscode/settings.json 中额外配置：

{
  // Configuration MCP
  "mcp.confluence.enabled": true,
  "mcp.confluence.baseUrl": "https://votre-domaine.atlassian.net",
  "mcp.confluence.defaultSpace": "SPACE_KEY",
  "mcp.jira.enabled": true,
  "mcp.jira.baseUrl": "https://votre-domaine.atlassian.net",
  "mcp.jira.defaultProject": "PROJECT_KEY",
  "mcp.servers": {
    "confluence": {
      "command": "mcp-confluence",
      "args": [
        "--space",
        "SPACE_KEY",
        "--page-id",
        "PAGE_ID"
      ]
    },
    "jira": {
      "command": "mcp-jira",
      "args": [
        "--project",
        "PROJECT_KEY",
        "--board",
        "BOARD_ID"
      ]
    }
  }
}

获取数值

  • Confluence (https://domaine.atlassian.net/wiki/spaces/MON_ESPACE/pages/12345678/Titre)

    • SPACE_KEY = MON_ESPACE
    • PAGE_ID = 12345678

  • Jira (https://domaine.atlassian.net/jira/software/c/projects/MON_PROJET/boards/99)

    • PROJECT_KEY = MON_PROJET
    • BOARD_ID = 99

我测试连接：成功 ✓

随后，我在 GitHub 上创建了一个仓库，用于存放文档模板，目录为 tpl_docs/：

  • TPL_README.md ：整体视图
  • TPL_README_IAM.md ：IAM
  • TPL_README_FW.md ：防火墙
  • TPL_README_SIZING.md ：容量规划
  • TPL_README_PROCEDURE.md ：操作流程
  • TPL_README_DEX.md ：运营手册

完整模板可在GitHub 仓库查看。

迭代 1：生成文档

我在 agents.md（编码助手的配置）中创建了一个自定义指令 create doc，一次性完成所有操作。

遇到的问题

  1. GitHub 认证：助手尝试在没有 token 的情况下访问我的私有仓库 → 通过在 agents.md 中明确指定 GitHub 连接器解决。
  2. 上下文超限（Claude Sonnet 4.5）在一次性生成多个文件时出现：
[INFO] Analyse du code Terraform... ✓
[INFO] Génération README.md... ✓
[INFO] Génération IAM.md... ✓
[INFO] Génération FW.md... ✓
[ERROR] Context length exceeded (125k tokens)
[FAIL] Process stopped

结论：必须将过程拆分。

迭代 2：迭代式方法

我修改 agents.md，将工作流拆成：

  1. 分析：检查 Terraform。
  2. 计划：列出要生成的文档。
  3. 执行：一次生成一份文档，每份文档对应一次对话。

日志示例：

NEW CONVERSATION> Analyse le code
Analyse du code Terraform... ✓
[INFO] Génération du plan de documentation... ✓

NEW CONVERSATION> Génération README.md
[INFO] Génération README.md... ✓

NEW CONVERSATION> Génération IAM.md
[INFO] Génération IAM.md... ✓

NEW CONVERSATION> Génération FW.md
[INFO] Génération FW.md... ✓

NEW CONVERSATION> Génération SIZING.md
[INFO] Génération SIZING.md... ✓

[SUCCESS] Documentation complète générée

结果

  • 分析 + 计划：✓
  • 顺序生成：✓（但耗时更长）
  • 完整文档：✓

迭代式流程可行，但仍然冗长。我不得不在模板的 prompts 中加入限制，确保输出不超过「5 行」。

迭代 3：运营文档（DEX）

在迭代 2 完成后，架构文档已经就绪。我随后加入了运营文档：SLA、DICT 表、监控、备份以及运营流程。

编码助手在生成具体操作步骤时表现尤为出色，能够给出精确的命令。示例：

gcloud compute instances attach-disk instance-1 --disk=disk-1 --zone=europe-west1-b

这种精准度避免了查找命令语法的时间浪费。

我新增了 TPL_README_DEX.md 和 TPL_README_PROCEDURE.md，并更新了 agents.md。冗长的问题仍在，但通过不断优化 prompts，输出质量持续提升。

Back to Blog

相关文章

阅读更多 »