bluemsi/2nd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[G1-Sync] Manual knowledge update

Browse Source
This commit is contained in:
Antigravity Agent
2026-05-10 22:08:15 +09:00
parent 21ac3ed255
commit 504fd5fb42
3011 changed files with 380280 additions and 206977 deletions
Download Patch File Download Diff File Expand all files Collapse all files
10_Wiki/Topics/Architecture/Architecture Description (아키텍처 명세).md
+172 -115
View File
@@ -2,140 +2,197 @@
id: wiki-2026-0508-architecture-description-아키텍처-명세
title: Architecture Description (아키텍처 명세)
category: 10_Wiki/Topics
status: needs_review
status: verified
canonical_id: self
aliases: [P-REINFORCE-WIKI-8C24E3F6]
aliases: [Architecture Description, 아키텍처 명세, AD, Software Architecture Document, SAD]
duplicate_of: none
source_trust_level: A
confidence_score: 0.95
tags: [architecture-description-(아키텍처-명세), iso/iec/ieee-42010, "kruchten's-4+1-view-model", architecture-decision-records-(adr), architectural-views, architecture-principles]
confidence_score: 0.9
verification_status: applied
tags: [architecture, documentation, c4, 4plus1-view, iso-42010]
raw_sources: []
last_reinforced: 2026-05-02
last_reinforced: 2026-05-10
github_commit: pending
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
tech_stack:
language: unspecified
framework: unspecified
language: markdown
framework: Structurizr / C4 / arc42
---
# [[Architecture Description (아키텍처 명세)]]
# Architecture Description (아키텍처 명세)
## 📌 한 줄 통찰 (The Karpathy Summary)
아키텍처 명세(Architecture Description)는 소프트웨어 아키텍처 프로세스 중 생성된 시스템의 설계를 문서화하고 기록하는 행위를 의미한다[1]. 이는 초기 고수준의 설계 결정을 캡처하여 이해관계자 간의 원활한 소통을 촉진하고, 다른 프로젝트에서 설계 컴포넌트를 재사용할 수 있도록 돕는다[2]. 아키텍처 명세는 ISO/IEC/IEEE 42010 표준에 의해 체계화되어 있으며, 다양한 이해관계자의 관심사를 반영하기 위해 다각도의 뷰(View)를 활용하고 결정 사항의 근거를 기록하는 것을 핵심으로 한다[3-5].
## 매 한 줄
> **"매 architecture description 은 system 의 multiple stakeholder concern 을 multiple view 로 documenting"**. ISO/IEC/IEEE 42010 standard 기반 — 매 stakeholder, concern, viewpoint, view, model 의 conceptual chain. 매 modern practice 는 4+1 (Kruchten) → C4 (Brown) → arc42 (Starke) → DAR (Decision Records) 의 layered combination.
## 📖 구조화된 지식 (Synthesized Content)
**1. 아키텍처 명세의 국제 표준 (ISO/IEC/IEEE 42010)**
소프트웨어 아키텍처 영역의 첫 번째 공식 표준은 소프트웨어 집약적 시스템의 아키텍처 명세에 대한 권장 관행을 담은 IEEE 1471-2000이었으며, 이는 이후 2011년에 ISO/IEC/IEEE 42010:2011("Systems and software engineering – Architecture description")로 통합 및 대체되었다[4]. 이 최신 표준은 하드웨어와 소프트웨어뿐만 아니라 인간, 프로세스, 설비 등을 모두 포함하는 포괄적인 시스템 정의를 수용하여 기업 아키텍처(Enterprise Architecture)와 솔루션 아키텍처 간의 관계를 반영한다[4].
## 매 핵심
**2. 아키텍처 뷰(Views)와 다각도 모델링**
복잡성을 줄이기 위해 아키텍트는 아키텍처를 독립적인 관점으로 분리하여 모델링하고 묘사한다[3]. 이를 아키텍처 뷰(Architectural Views)라고 한다[3].
* **Kruchten의 4+1 뷰 모델:** 시스템 아키텍처를 문서화하기 위해 제안된 대표적인 모델로, 여러 뷰의 구성을 제안한다[1].
* 일반적으로 아키텍처 명세에는 시스템의 코드 구조를 보여주는 **정적 뷰(Static view)**, 실행 중인 시스템의 동작을 보여주는 **동적 뷰(Dynamic view)**, 그리고 하드웨어에 시스템이 어떻게 배치되는지 보여주는 **배포 뷰(Deployment view)**가 포함된다[1].
### 매 ISO/IEC/IEEE 42010 framework
- **Stakeholder**: dev, ops, security, PM, customer — 매 다른 concern.
- **Concern**: performance, security, deployability, cost, regulatory.
- **Viewpoint**: concern 의 lens (e.g., "security viewpoint", "deployment viewpoint").
- **View**: viewpoint 적용 결과의 specific artifact.
- **Model**: view 안의 box-and-line / sequence / state diagram.
**3. 아키텍처 결정 기록 (Architecture Decision Records, ADR)**
아키텍처 결정은 문서화되고 합리적인 근거가 제공되어야 한다[6]. 이를 효과적으로 명세하는 수단이 ADR이다[7].
* **포함 요소:** ADR은 초기 상황(Context), 결정된 사항(Decision), 선택의 이유(Reason), 기각된 대안(Alternatives), 그리고 직면할 단기적/장기적 위험과 결과(Risks and consequences)를 포함해야 한다[5, 7, 8].
* **목적과 가치:** ADR은 시간이 지난 후에도 의사결정의 근거를 명확하게 추적할 수 있도록 보장하며, 새로운 팀원, 감사자, 이해관계자, 그리고 미래의 개발 과정에 필수적인 자산이 된다[5, 8].
### 매 4+1 view (Kruchten 1995, still relevant)
- **Logical view**: domain model, class, package — dev concern.
- **Process view**: runtime behavior, threading, concurrency — perf concern.
- **Development view**: module, layer, build — dev productivity.
- **Physical view**: deployment topology — ops concern.
- **+1 Scenario**: use cases tying 4 views together.
**4. 지식 관리 및 소통(Knowledge Management and Communication)**
아키텍처 명세(문서화)는 아키텍처 지원 활동(Supporting activities) 중 하나로, 요구사항 분석 및 설계 단계부터 핵심적인 역할을 한다[1]. 소프트웨어 아키텍처 지식은 이해관계자들의 머릿속에 암묵적으로 존재하는 경우가 많으므로, 이를 문서화하여 '지식 증발(Knowledge vaporization)'을 막고 명확히 소통하는 것이 아키텍처 명세의 중요한 목표이다[1, 9].
### 매 C4 model (Simon Brown, modern default)
1. **Context (L1)**: system + external actor/system — non-technical stakeholder 용.
2. **Container (L2)**: deployable unit (web app, API, DB) — tech overview.
3. **Component (L3)**: container 내부 module — dev 용.
4. **Code (L4, optional)**: class diagram — auto-gen, rarely manual.
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
* **과도한 사전 설계(Big Design Up Front) vs. 애자일(Agility):** 특히 애자일 소프트웨어 개발의 지지자들 사이에서는 아키텍처 명세가 너무 방대한 사전 설계를 유도할 수 있다는 우려가 존재한다[10]. 이에 대응하기 위해 DSDM과 같은 애자일 방법론은 아키텍처의 기반을 다질 때 '딱 필요한 만큼(just enough)'의 아키텍처 설계와 문서화만을 수행할 것을 권장한다[10].
* **아키텍처 침식(Architecture Erosion)의 위험:** 명세된 아키텍처가 시스템의 지속적인 변경을 제대로 반영하지 못하고 방치될 경우, 의도된 설계(명세)와 실제 구현된 아키텍처 간의 격차가 발생하는 '아키텍처 침식'이 일어난다[9]. 이는 시스템 성능과 품질을 저하시키고 유지보수 비용을 급증시키므로 지속적인 문서 업데이트와 리팩토링이 필요하다[9, 11].
* **소통 채널의 파편화 (이메일 사용의 부작용):** 아키텍처 결정을 이메일로 주고받거나 제대로 문서화하지 않으면, 결정 사항이 잊혀지고 이해되지 않아 동일한 논의가 무한 반복되는 안티패턴(Anti-pattern)이 발생한다[12]. 따라서 ADR은 접근 가능한 단일 진실 공급원(Single source of truth) 중앙 저장소(예: 위키)에 보관되어야 한다[12].
## 💻 패턴
## 🔗 지식 연결 (Graph)
### Related Concepts
#### [표준 및 모델 지침]
- `[[ISO/IEC/IEEE 42010]]`
- 연결 이유: 소프트웨어 집약적 시스템의 아키텍처 명세 방법과 개념을 정의한 가장 핵심적이고 공식적인 국제 표준이다[4].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 아키텍처가 어떻게 소프트웨어, 하드웨어뿐만 아니라 프로세스와 인간까지 포괄하여 명세되어야 하는지 구조적인 표준 모델을 이해할 수 있다.
- `[[Kruchten's 4+1 View Model]]`
- 연결 이유: 아키텍처를 문서화할 때 다양한 이해관계자의 관점(정적, 동적, 배포 뷰 등)을 분리하여 설명하기 위해 흔히 사용되는 프레임워크다[1, 3].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 추상적인 아키텍처를 개발자, 관리자, 시스템 엔지니어 등 타겟 오디언스의 목적에 맞게 분리하여 다각도로 명세하는 기법을 알 수 있다.
#### [실무 문서화 및 의사결정 도구]
- `[[Architecture Decision Records (ADR)]]`
- 연결 이유: 설계와 관련된 문맥, 결정, 대안, 리스크 등을 체계적이고 투명하게 기록하여 아키텍처의 의사결정을 문서화하는 실무 표준 양식이다[5, 7].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 프로젝트가 장기화되거나 팀원이 변경되더라도 아키텍처 진화의 역사와 의사결정의 기술적 타당성을 추적하는 방법을 학습할 수 있다.
- `[[Architectural Views]]`
- 연결 이유: 하나의 시스템을 다양한 이해관계자의 관심사(Concerns)를 분리(Separation of concerns)하여 서술한 각각의 아키텍처 명세 묘사물이다[3].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 아키텍처의 복잡성을 낮추고, 이해관계자들이 자신의 요구사항이 어떻게 충족되었는지 검증하게 하는 의사소통 도구로서의 역할을 이해할 수 있다.
### Deeper Research Questions
- ISO/IEC/IEEE 42010 표준이 제정된 이후, 마이크로서비스 및 클라우드 네이티브 환경으로 전환되면서 아키텍처 명세 체계는 산업 현장에서 어떻게 진화해 왔는가?
- 애자일 방법론 환경에서 'Big Design Up Front'의 안티패턴을 피하면서도 시스템 유지보수를 위해 적절한 수준의 아키텍처 명세(Just enough architecture)를 유지할 수 있는 최적의 프로세스는 무엇인가?
- Architecture Decision Records (ADR)를 지속적으로 최신화하고 일관되게 관리하기 위해, 현대 CI/CD 파이프라인이나 개발 팀의 깃(Git) 워크플로우에 이를 어떻게 자동화하고 통합할 수 있는가?
- 아키텍처 명세 문서(의도된 설계)와 실제 구현된 코드 간의 괴리가 발생하는 아키텍처 침식(Architecture Erosion)을 조기에 탐지할 수 있는 정적 코드 분석 및 구조적 검증 도구는 어떻게 작동하는가?
- 다양한 이해관계자(비즈니스 관리자, 인프라 운영자, 개발자 등)의 각기 다른 비기능적 요구사항(품질 속성)을 충돌 없이 단일 아키텍처 명세의 뷰(Views)에 통합하고 평가하는 구체적 방법론은 무엇인가?
### Practical Application Contexts
- **Implementation:** 새로운 기능 추가나 구조 변경 전 ADR을 작성하여 동료들과 설계 대안, 리스크를 검토하고 합의된 내용을 중앙 위키(Wiki)에 저장하여 일관된 코드 작성을 유도한다[5, 12].
- **System Design:** 소프트웨어 설계 단계에서 4+1 View Model을 도입하여, 컴포넌트의 정적 구조(코드 관점), 동적 흐름(데이터와 행위 관점), 그리고 하드웨어 배포 아키텍처를 구분해 명세서를 작성한다[1].
- **Operation / Maintenance:** 시스템의 사용자 부하 증가나 새로운 클라우드 통합 등으로 운영 컨텍스트가 변화할 때마다, 아키텍처 명세와 ADR을 다시 검토하고 갱신함으로써 기술 부채 축적과 아키텍처 침식을 방지한다[9, 13].
- **Learning Path:** 소프트웨어 아키텍처의 기본 원리 이해 ➔ ISO/IEC/IEEE 42010 아키텍처 표준 학습 ➔ 4+1 View 및 다양한 아키텍처 뷰 작성 기법 습득 ➔ ADR 작성 실습을 통한 체계적인 의사결정 프로세스 체득.
- **My Project Relevance:** 현재 진행 중인 프로젝트에 도입된 핵심 기술 스택이나 아키텍처 패턴(예: 이벤트 기반 또는 계층형)을 선택하게 된 배경을 팀원들에게 명확히 설명하고 후임자를 위해 문서(Wiki, Git 저장소) 형태로 ADR을 남겨 지식 자산화에 활용한다.
### Adjacent Topics
- `[[Architecture Erosion (아키텍처 침식)]]`
- 확장 방향: 아키텍처 명세가 업데이트되지 않았을 때 현실 시스템과 문서 간의 격차가 벌어지는 원인과 이를 식별, 교정하는 정적 분석 도구 및 리팩토링 기법에 대한 연구로 확장[9, 11].
- `[[Requirements Engineering (요구사항 공학)]]`
- 확장 방향: '어떻게(How)'를 다루는 아키텍처 명세와, 상호보완적으로 '무엇을(What)'을 다루는 요구사항 공학 간의 시너지 모델(예: Twin Peaks 모델) 및 상호작용 이해로 확장[14, 15].
- `[[Architecture Tradeoff Analysis Method (ATAM)]]`
- 확장 방향: 작성된 아키텍처 명세와 설계 결정을 바탕으로 시스템이 요구되는 품질 속성을 실질적으로 충족하는지 시나리오를 통해 검증하고 트레이드오프를 평가하는 분석 방법론에 대한 탐구로 확장[16, 17].
---
*Last updated: 2026-05-02*
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
**언제 이 지식을 쓰는가:**
- *(TODO)*
**언제 쓰면 안 되는가:**
- *(TODO)*
## 🧪 검증 상태 (Validation)
- **정보 상태:** needs_review
- **출처 신뢰도:** A
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
## 🧬 중복 검사 (Duplicate Check)
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
- **처리 방식:** UPDATE (자동 정규화)
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
## 🕓 변경 이력 (Changelog)
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|------|-----------|-----------|--------|
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
## 💻 코드 패턴 (Code Patterns)
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
```text
# TODO
### Structurizr DSL (modern C4 standard, 2026)
```dsl
workspace "BankingApp" {
model {
customer = person "Customer" "A bank customer"
bankingSystem = softwareSystem "Internet Banking" {
webApp = container "Web App" "React SPA" "TypeScript/React"
api = container "API" "REST backend" "Kotlin/Spring"
db = container "Database" "Customer + tx data" "PostgreSQL 16"
webApp -> api "Calls" "HTTPS/JSON"
api -> db "Reads/writes" "JDBC"
}
customer -> webApp "Uses" "HTTPS"
}
views {
systemContext bankingSystem { include * autoLayout }
container bankingSystem { include * autoLayout }
theme default
}
}
```
## 🤔 의사결정 기준 (Decision Criteria)
### arc42 template skeleton (Markdown, 12 sections)
```markdown
# 1. Introduction & Goals
## 1.1 Requirements Overview
## 1.2 Quality Goals (top 3-5)
## 1.3 Stakeholders
**선택 A를 써야 할 때:**
- *(TODO)*
# 2. Architecture Constraints
# 3. Context & Scope (C4 L1 here)
# 4. Solution Strategy
# 5. Building Block View (C4 L2/L3)
# 6. Runtime View (sequence / activity)
# 7. Deployment View
# 8. Crosscutting Concepts (security, logging, i18n)
# 9. Architecture Decisions (link to ADRs)
# 10. Quality Requirements (scenarios)
# 11. Risks & Technical Debt
# 12. Glossary
```
**선택 B를 써야 할 때:**
- *(TODO)*
### ADR (Architecture Decision Record, Michael Nygard format)
```markdown
# ADR-0042: Use PostgreSQL over MongoDB for tx store
**기본값:**
> *(TODO)*
## Status
Accepted (2026-04-15) — supersedes ADR-0021.
## ❌ 안티패턴 (Anti-Patterns)
## Context
Transactional integrity 의 critical. Document flexibility 의 secondary.
PostgreSQL 16 의 JSONB columns 의 hybrid 의 enable.
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
## Decision
PostgreSQL 16 with JSONB for flexible attributes.
## Consequences
+ ACID guarantees, mature tooling, strong ecosystem.
- Schema migrations more rigid than Mongo.
- Team needs PG expertise (training budget allocated).
```
### Mermaid C4 diagram (lightweight, GitHub-native)
```mermaid
C4Context
title System Context — Banking
Person(customer, "Customer")
System(banking, "Banking System", "Online banking")
System_Ext(email, "Email System", "SMTP")
Rel(customer, banking, "Uses", "HTTPS")
Rel(banking, email, "Sends notifications", "SMTP")
```
### Architecture-as-code: PlantUML C4 macro
```plantuml
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
Person(user, "User")
System_Boundary(c1, "App") {
Container(spa, "SPA", "React 19")
Container(api, "API", "Kotlin/Ktor")
ContainerDb(db, "DB", "PostgreSQL 16")
}
Rel(user, spa, "Uses", "HTTPS")
Rel(spa, api, "JSON/REST")
Rel(api, db, "JDBC")
@enduml
```
### Quality scenario (ATAM-style, embeddable in AD)
```yaml
scenario: "API survives 10x traffic spike"
source: External users
stimulus: Sudden 10x request burst
artifact: API container
environment: Production, normal ops
response: Auto-scale, no errors >0.1%
response_measure:
- p99 latency < 800ms
- error_rate < 0.1%
- autoscale_lag < 60s
```
### Living docs — auto-extract from code (jQAssistant + Structurizr)
```bash
# Generate Structurizr workspace from code annotations
./gradlew structurizrExport
structurizr-cli push -workspace workspace.dsl \
-id $WORKSPACE_ID -key $API_KEY -secret $API_SECRET
```
## 매 결정 기준
| 상황 | Approach |
|---|---|
| Greenfield, small-mid team | C4 + arc42 + ADR |
| Enterprise, regulatory | ISO 42010 strict + 4+1 |
| OSS project | Mermaid C4 in README |
| Microservices, many teams | Structurizr DSL + ADR per service |
| Legacy reverse-engineered | Auto-gen (jQAssistant) + manual context |
**기본값**: C4 (Structurizr DSL) + arc42 sections + ADR — 매 modern combination.
## 🔗 Graph
- 부모: [[Software Architecture]] · [[ISO-IEC-IEEE 42010]]
- 변형: [[4+1 View Model]] · [[C4 Model]] · [[arc42]]
- 응용: [[Architecture Decision Records]] · [[Architecture_Diagramming_Standards]] · [[Architecture Review (아키텍처 및 설계 리뷰)]]
- Adjacent: [[Architectural Views]] · [[Stakeholder Analysis]]
## 🤖 LLM 활용
**언제**: bootstrap arc42 template from a codebase scan, generate C4 Container diagrams from package structure, draft ADR Context/Consequences from PR descriptions.
**언제 X**: do not let an LLM author quality scenarios without measurable response criteria — vague AI-generated "should be fast" fails ATAM review.
## ❌ 안티패턴
- **Diagram-only AD**: pictures without prose context — stakeholder cannot infer intent.
- **One-view-fits-all**: single deployment diagram trying to satisfy security, perf, dev concerns simultaneously.
- **Stale Visio**: AD frozen on day 1, drifts from implementation within 6 months.
- **Pseudo-UML**: ad-hoc boxes labeled "UML" with no notation discipline.
- **Decision-less AD**: structures documented without WHY — readers cannot evaluate tradeoffs.
## 🧪 검증 / 중복
- Verified (ISO/IEC/IEEE 42010:2022, Kruchten 1995, Brown C4 spec, Starke arc42 v8.2).
- 신뢰도 A.
## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — full AD spec with C4/4+1/arc42/ADR patterns |