vlaskos/architecture-documentation-skill

소프트웨어 아키텍처 문서화하기

아키텍처 문서는 이해관계자가 시스템이 수명을 다할 때까지 회의에서 묻지 않도록 미리 답변을 제공합니다: 이것은 어떻게 구성되어 있나요? 왜 이렇게 되었나요? X를 변경하려면 어디를 봐야 하나요? Y 조건에서도 견딜 수 있나요? 훌륭한 문서는 이런 질문을 한 번에, 글로, 각 독자가 실제로 사용할 수 있는 형태로 답합니다.

이 스킬은 그러한 문서를 만들고, 다른 사람이 작성한 문서를 검토하기 위한 방법입니다. 단일 저작권 텍스트가 아닌 공개적으로 무료로 제공되는 표준과 모델을 기반으로 합니다.

• ISO/IEC/IEEE 42010 — 아키텍처 설명에 대한 국제 표준입니다. 문서 전반에서 사용하는 용어(이해관계자, 관심사, 뷰포인트, 뷰, 모델, 아키텍처 결정, 근거)를 제공합니다.
• C4 모델(Simon Brown) — 컨텍스트, 컨테이너, 컴포넌트, 코드의 네 가지 확대 수준으로 구성된 가벼운 구조적 다이어그램 세트입니다.
• 4+1 뷰 모델(Philippe Kruchten) — 논리, 프로세스, 개발, 물리, 그리고 이들을 연결하는 시나리오의 다섯 가지 동시적 관점입니다.
• arc42 — 크리에이티브 커먼즈 라이선스 문서 템플릿으로, 섹션 구조가 전체 아키텍처 설명을 위한 실용적인 뼈대를 제공합니다.
• 아키텍처 결정 레코드(Michael Nygard가 대중화한 ADR 형식) — 중요한 결정마다 하나의 짧은 파일입니다.

방법

문서화는 누가 읽는가와 그들이 결정하거나 수행해야 할 것이 무엇인가에 의해 결정됩니다. 다음 순서로 작업하세요.

1. 이해관계자와 그들의 관심사를 식별하세요. 아키텍처에 의존하는 사람들(개발자, 운영자, 보안 검토자, 제품 소유자, 통합자, 감사자)을 나열하고 각자가 문서에서 무엇을 답변받길 원하는지 파악하세요. 관심사는 누군가에게 중요한 질문이나 품질 속성입니다: "다운타임 없이 배포할 수 있나요?", "고객 데이터는 어디에 저장되나요?", "새로운 결제 제공자를 어떻게 추가하나요?" 관심사는 이후의 모든 것을 결정합니다. references/viewpoints-and-views.md를 참조하세요.

2. 관심사를 다루는 뷰포인트를 선택하세요. 뷰포인트는 재사용 가능한 종류의 뷰입니다: 한 가지 유형의 표현을 구성하기 위한 규칙(표시할 요소, 관계, 표기법)입니다. 모든 중요한 관심사를 함께 다루는 가장 작은 뷰포인트 집합을 선택하세요. 아무도 필요로 하지 않는 뷰는 작성하지 마십시오. references/view-catalog.md를 참조하세요.

3. 뷰를 구축하세요. 각 뷰는 하나의 뷰포인트에서 시스템을 한 번 표현한 것입니다: 다이어그램과 그를 설명하는 산문입니다. 대부분의 시스템에는 구조적 뷰(구성 요소와 그 의존 관계), 런타임 뷰(실행 시간에 발생하는 것: 프로세스, 흐름, 상호 작용), 배포 뷰(소프트웨어가 인프라에 매핑되는 방식)가 필요합니다. 타이밍이나 순서가 핵심인 부분에는 행동 뷰를 추가하세요. C4 레벨과 4+1 관점은 이를 구현하는 구체적이고 입증된 방법입니다. references/view-catalog.md를 참조하세요.

4. 결정과 그 근거를 기록하세요. 아키텍처 문서에서 가장 가치 있고 가장 자주 누락되는 부분은 이유입니다. 각 중요한 결정(컨텍스트, 고려된 옵션, 선택, 결과)을 아키텍처 결정 레코드로 기록하세요. 근거는 다음 사람이 추측 대신 안전하게 시스템을 변경할 수 있게 해줍니다. references/decisions-and-rationale.md를 참조하세요.

5. 설명을 조립하고 방향을 추가하세요. 뷰의 모음은 문서가 아닙니다. 연결 조직을 추가하세요: 한 페이지 분량의 시스템 개요, 범위 및 컨텍스트 설명, 용어집, 그리고 뷰 간의 관계(두 뷰에서 동일한 요소가 보이면 독자에게 주요 혼란 원인이 되므로 이를 해결)에 대한 명시적 설명입니다. 전체 섹션 뼈대는 references/documentation-template.md를 사용하세요.

6. 배포 전에 검토하세요. references/review-checklist.md를 기준으로 문서를 검토하세요. 두 가지 실패 모드는 불완전성(어떤 뷰도 다루지 않는 관심사)과 읽기 어려움(키가 없는 다이어그램, 정의되지 않은 용어, 독자가 무엇을 보고 있는지에 대한 설명 부재)입니다.

이 스킬을 사용하는 방법

• 처음부터 시작하는 경우 → 위의 여섯 단계를 따르고 references/documentation-template.md를 대상 구조로 사용하세요.
• 무엇을 쓸지 결정하는 경우 → references/viewpoints-and-views.md(관심사 → 뷰포인트)와 references/view-catalog.md(뷰 유형 카탈로그).
• 결정을 기록하는 경우 → references/decisions-and-rationale.md(ADR 형식 및 예제).
• 기존 문서를 검토하는 경우 → references/review-checklist.md.
• 프레임워크 간 선택 또는 매핑하는 경우 → references/frameworks-map.md.

원칙

• 독자를 위해 쓰고, 완전성을 위해 쓰지 마세요. 모든 뷰, 다이어그램, 단락은 이해관계자의 관심사로 추적 가능해야 합니다. 누가 그것을 필요로 하는지 말할 수 없다면 잘라내세요.
• 모든 다이어그램에는 키가 필요합니다. "당연해 보이는" 표기법은 그렇지 않습니다. 상자와 선이 무엇을 의미하는지 명시하세요. 설명되지 않은 다이어그램은 잘못될 가능성이 있는 추측에 불과합니다.
• 결정을 내릴 때 근거를 기록하세요. 결정은 내리는 순간에는 기록하기 쉽지만 나중에 재구성하는 것은 비용이 많이 듭니다.
• 코드와 가깝게 유지하고 최신 상태를 유지하세요. 현실과 동떨어진 문서는 사람들이 신뢰하기 때문에 없는 것보다 더 나쁩니다. 유지 관리하지 않을 큰 문서보다 유지 관리할 작은 문서를 선호하세요.
• 시스템의 위험에 따라 깊이를 설정하세요. 잘못되었을 때 비용이 많이 드는 부분은 자세히 문서화하고 나머지는 간략히 스케치하세요.