Antigravity Agent
3.3 KiB
3.3 KiB
id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, tags, raw_sources, last_reinforced, github_commit
| id | title | category | status | canonical_id | aliases | duplicate_of | source_trust_level | confidence_score | tags | raw_sources | last_reinforced | github_commit | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| P-REINFORCE-WIKI-DEV-EXECUTABLE-DOCS | 실행 가능한 문서화 전략 (Executable Documentation) | 10_Wiki/💻 Topics_Dev | verified |
|
A | 1.0 |
|
|
2026-05-02 |
실행 가능한 문서화 전략 (Executable Documentation)
1. 개요
실행 가능한 문서(Executable Documentation)는 시스템의 기대 동작을 설명하는 동시에, 실제 코드로 실행되어 그 진실성을 검증할 수 있는 형태의 문서를 의미한다. 전통적인 정적 문서가 코드와 분리되어 빠르게 낙후되는 문제를 해결하며, 시스템의 현재 상태를 가장 정확하게 대변하는 지표가 된다.
2. 주요 구현체
- 테스트 코드 (Test Code): 시스템의 설계 철학과 비즈니스 로직을 명시하는 가장 강력한 문서. 단위/통합 테스트를 통해 모듈의 책임과 상호작용을 실행 가능한 형태로 보존한다.
- API 명세 (OpenAPI/AsyncAPI): 기계가 읽을 수 있는 명세를 기반으로 대화형 문서(Swagger 등), 서버 스텁, 클라이언트 SDK를 자동 생성하여 구현과 문서의 일치를 보장한다.
- 코드로 관리하는 다이어그램 (Diagrams as Code): Mermaid, PlantUML 등을 사용해 텍스트 기반으로 아키텍처를 정의하고 Git으로 버전 관리하여 설계의 진화 과정을 추적한다.
3. 실전 활용 가치
- 신뢰할 수 있는 진실의 근원 (SSOT): 문서와 실제 구현이 일치하는지 자동으로 검증할 수 있어 신규 개발자가 믿고 의지할 수 있는 가이드가 됨.
- 실험적 학습: 테스트 코드의 입력을 변경하고 시스템의 반응을 관찰함으로써, 정적 독해만으로는 알 수 없는 런타임 특성을 빠르게 습득.
- 유지보수 안전망: 코드 변경 시 관련 테스트(문서)가 실패함으로써 의도치 않은 부수 효과(Side-effect)를 조기에 탐지.
4. 트레이드오프 및 주의사항
- 장점: 문서 최신화 자동화, 설계 의도 보존, 시스템 이해도 증진.
- 단점: 테스트 코드 자체의 복잡성 및 유지보수 부담 증가, 초기 도구 설정 및 팀의 엄격한 규율 요구.
- 주의: 테스트 코드가 '무엇을(What)' 하는지는 보여주지만, '왜(Why)' 그렇게 설계했는지는 주석이나 별도의 설계 의도 기록(ADR)이 필요할 수 있음.
5. 지식 연결 (Related)
- Static_and_Dynamic_Analysis: 실행 가능한 문서를 검증하고 활용하는 분석 기법.
- API_First_Architecture: 실행 가능한 API 계약을 최우선으로 설계하는 방법론.
- Codebase_Maps_and_Interactive_Tours: 실행 가능한 문서를 활용해 시스템 탐색 경험을 고도화하는 도구.
🧪 검증 상태 (Validation)
- 정보 상태: 검증 완료 (Verified)
- 출처 신뢰도: A
- 검토 이유: 코드와 문서의 괴리를 해결하고 지속 가능한 지식 관리 체계를 구축하기 위한 필수 전략 정립.