Antigravity Agent
47 lines
3.6 KiB
Markdown
47 lines
3.6 KiB
Markdown
---
|
|
id: P-REINFORCE-WIKI-DEV-EXECUTABLE-DOCS
|
|
title: "실행 가능한 문서와 테스트 주도 지식 관리 (Executable Documentation)"
|
|
category: "10_Wiki/💻 Topics_Dev"
|
|
status: verified
|
|
canonical_id: ""
|
|
aliases: ["실행 가능한 문서", "Executable Documentation", "테스트 문서화", "살아있는 문서"]
|
|
duplicate_of: ""
|
|
source_trust_level: A
|
|
confidence_score: 1.0
|
|
tags: ["Documentation", "Testing", "QA", "Automation", "Knowledge_Management"]
|
|
raw_sources: ["Datacollector_Export_2026-05-02"]
|
|
last_reinforced: 2026-05-02
|
|
github_commit: ""
|
|
---
|
|
|
|
# [[실행 가능한 문서와 테스트 주도 지식 관리 (Executable Documentation)]]
|
|
|
|
## 1. 개요
|
|
실행 가능한 문서(Executable Documentation)는 시스템의 기대 동작을 명시할 뿐만 아니라, 실제 코드로 실행되어 그 진위 여부를 즉각적으로 검증할 수 있는 형태의 문서를 의미한다. 전통적인 정적 문서가 코드와 분리되어 노후화되는 한계를 극복하고, 시스템의 최신 상태를 항상 반영하는 '살아있는 지식'의 역할을 수행한다.
|
|
|
|
## 2. 주요 구현 형태
|
|
- **테스트 코드 (Test Code)**: 유닛 테스트와 통합 테스트는 함수나 컴포넌트의 사용법과 기대 결과값을 담고 있는 가장 강력한 실행 가능한 문서다.
|
|
- **API 명세 (OpenAPI/Swagger)**: 기계 해독 가능한 사양 파일을 통해 대화형 문서, 클라이언트 SDK, Mock 서버를 자동 생성하여 문서와 구현체 간의 일관성 보장.
|
|
- **다이어그램 코드화 (Diagrams as Code)**: Mermaid, Structurizr 등을 사용하여 아키텍처를 텍스트로 정의. 코드와 동일한 저장소에서 버전 관리되어 실시간 업데이트 가능.
|
|
- **문서화 테스트 (Doctest)**: 코드 주석 내에 실행 가능한 예시 코드를 포함시켜, 문서의 예제가 실제 코드와 일치하는지 자동으로 검증.
|
|
|
|
## 3. 엔지니어링 가치
|
|
- **신뢰성 있는 온보딩**: 신규 개발자가 방치된 문서를 읽는 대신, 잘 작성된 테스트 코드를 실행하며 시스템의 런타임 반응을 관찰함으로써 정확한 멘탈 모델 형성.
|
|
- **문서 노후화 방지**: 코드가 변경되었을 때 테스트가 실패하거나 문서가 빌드되지 않도록 하여, 구현과 지식 간의 '아키텍처 드리프트' 현상 차단.
|
|
- **계약 기반 개발 (Contract-based Development)**: API 명세가 문서이자 계약이 되어, 백엔드와 프론트엔드가 병렬로 개발을 진행할 수 있는 기술적 토대 제공.
|
|
|
|
## 4. 트레이드오프 및 주의사항
|
|
- **테스트 스위트의 비대화**: 실행 가능한 문서로서의 가치를 위해 테스트를 과도하게 조직화하면 오히려 유지보수 비용이 상승할 수 있음.
|
|
- **모호한 경계 설정**: 테스트가 격리되지 않고 상호 의존성을 가지게 되면, 문서로서의 정확성과 신뢰도가 떨어지므로 명확한 테스트 경계(Boundary) 설정 필수.
|
|
- **초기 도입 비용**: 명세 기반 자동화 툴체인을 구축하고 팀 내에 문서화 문화를 정착시키는 데 지속적인 노력이 요구됨.
|
|
|
|
## 5. 지식 연결 (Related)
|
|
- [[Documentation_Strategy]]: 시스템 전체의 문서화 로드맵과 뷰.
|
|
- [[Mermaid_Diagrams]]: 텍스트 기반 다이어그램의 구체적 작성 기법.
|
|
- [[Test_Driven_Development]]: 실행 가능한 문서를 먼저 작성하며 개발하는 방법론.
|
|
|
|
## 🧪 검증 상태 (Validation)
|
|
- **정보 상태**: 검증 완료 (Verified)
|
|
- **출처 신뢰도**: A
|
|
- **검토 이유**: 문서의 신뢰성을 확보하고 코드와 지식 간의 동기화 문제를 해결하기 위한 지능형 문서화 표준 정립.
|