software

DAT as Code: AI를 활용한 기술 문서 자동화

발행: (2025년 12월 15일 오후 05:39 GMT+9)
7 min read
원문: Dev.to

Source: Dev.to

Introduction

작년에는 DAT(기술 아키텍처 파일) 현대화 가이드를 작성했습니다. 1년이 지나 코딩 어시스턴트와 그 커넥터가 등장하면서, AI를 활용해 DAT를 실제로 어떻게 유지보수할 수 있을까? 라는 궁금증이 생겼습니다.

Infra‑as‑code 프로젝트에 적용해 보았습니다.
목표: 제로부터 시작해 최소한의 노력으로 완전한 문서(아키텍처 + 운용)를 만들기.
스포일러: 몇 시간만 설정하면 바로 동작합니다.

La découverte : templates + prompts

코딩 어시스턴트를 처음 테스트했을 때는 마크다운 파일에 구조(제목, 섹션)를 넣고 HTML 주석 안에 지시문을 삽입했습니다.

예시:

## 🏗️ Prérequis

## Description de la gestion IAM

코딩 어시스턴트는 그 구조를 따라가며 각 섹션을 지시사항에 맞게 채워줍니다.
단순해 보이지만, 전체 문서 스타일의 일관성을 유지하는 데 가장 효과적인 방법이었습니다.

Le problème : 3 outils à synchroniser

일반적인 프로젝트에서는 다음 세 가지를 오가며 작업합니다.

  • GitHub (코드): markdown을 doc‑as‑code 형태로 관리
  • Confluence (문서): 검색과 가독성을 위해 사용
  • Jira (티켓): 이슈와 프로젝트 추적

Confluence 문서를 수동으로 최신 상태로 유지하는 것은 고통입니다.
코드와 함께 GitHub에서 문서를 작성하고 싶지만, 검색 측면에서는 덜 편리합니다.
이상적인 흐름: 코드를 기준으로 문서를 작성하고, 그에 따라 Confluence를 자동으로 업데이트하며, GitHub 문서에 대한 링크와 참조를 포함하는 것입니다.

Diagramme GitHub‑Confluence‑Jira

La solution : MCP (Model Context Protocol)

MCP는 코딩 어시스턴트가 외부 서비스와 대화할 수 있게 해주는 커넥터입니다. 이번 프로젝트에서 핵심이 되는 세 가지를 선정했습니다.

  • Context7: 문서가 표준을 준수하는지 검증하고 누락된 부분을 찾아줍니다.
  • GitHub: (내 경우 Terraform) 코드를 읽어 아키텍처 정보를 추출합니다.
  • Atlassian: Confluence와 Jira와 연동합니다.

IDE coding assistant + MCP

Setup

IDE(VsCode 기준)에서 3개의 MCP를 설치했습니다(다른 IDE인 Cursor, IntelliJ 등에서도 동작합니다).
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"
      ]
    }
  }
}

Récupérer les valeurs

  • 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

연결 테스트 결과: 성공 ✓

그 다음, tpl_docs/ 디렉터리에 문서 템플릿을 담은 GitHub 레포를 만들었습니다:

  • 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 레포지토리에서 확인할 수 있습니다.

Itération 1 : créer la documentation

agents.md(코딩 어시스턴트 설정) 안에 create doc 라는 커스텀 명령을 만들어 한 번에 모든 작업을 수행하도록 했습니다.

Problèmes rencontrés

  1. GitHub 인증: 어시스턴트가 비공개 레포에 토큰 없이 접근하려고 해서 실패 → 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

결론: 프로세스를 분할해야 함.

Itération 2 : approche itérative

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

Résultats

  • 분석 + 계획: ✓
  • 순차적 생성: ✓ (시간은 더 걸림)
  • 전체 문서: ✓

반복 프로세스는 잘 동작하지만 출력량이 많아(verbose) 문제가 있습니다. 템플릿 프롬프트를 조정해 “5줄 이하”로 제한하도록 개선했습니다.

Itération 3 : documentation d’exploitation (DEX)

2단계가 끝난 뒤 아키텍처 문서는 완성되었습니다. 이제 운영 문서(DEX)를 추가했습니다: 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를 업데이트했습니다. 여전히 출력이 다소 길지만, 프롬프트 개선 작업을 지속적으로 적용하고 있습니다.

Back to Blog

관련 글

더 보기 »