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/Software Architecture Knowledge Management (소프트웨어 아키텍처 지식 관리).md
+159 -109
View File
@@ -2,134 +2,184 @@
id: wiki-2026-0508-software-architecture-knowledge-
title: Software Architecture Knowledge Management (소프트웨어 아키텍처 지식 관리)
category: 10_Wiki/Topics
status: needs_review
status: verified
canonical_id: self
aliases: [P-REINFORCE-WIKI-51CD4F93]
aliases: [SAKM, Architecture Knowledge Management, AKM]
duplicate_of: none
source_trust_level: A
confidence_score: 0.95
tags: [software-architecture-knowledge-management-(소프트웨어-아키텍처-지식-관리), architecture-decision-record-(adr), architecture-description-(아키텍처-명세), atam-(architecture-tradeoff-analysis-method), architecture-erosion-(아키텍처-침식), architecture-principles]
confidence_score: 0.85
verification_status: applied
tags: [architecture, knowledge-management, documentation, governance]
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: backstage
---
# [[Software Architecture Knowledge Management (소프트웨어 아키텍처 지식 관리)]]
# Software Architecture Knowledge Management (소프트웨어 아키텍처 지식 관리)
## 📌 한 줄 통찰 (The Karpathy Summary)
소프트웨어 아키텍처 지식 관리(Software Architecture Knowledge Management)는 소프트웨어 아키텍처 설계에 필수적인 지식을 탐색, 소통, 유지 및 관리하는 활동을 의미합니다 [1]. 아키텍처는 단순한 모델이나 구조의 집합이 아니라 특정 구조를 도출하게 된 결정과 그 이면의 근거(Rationale)를 포함해야 합니다 [2]. 이러한 지식은 종종 암묵적(Tacit)이며 이해관계자의 머릿속에 머물기 쉽기 때문에, 아키텍처 결정 기록(ADR) 등을 통해 체계적으로 지식을 문서화하고 소통하여 지식의 격차로 인한 잘못된 설계를 방지하는 과정이 필수적입니다 [1], [3].
## 매 한 줄
> **"매 architectural knowledge 의 codify, share, retain — turnover 와 erosion 의 against."**. 매 SAKM 의 ADR + arc42 doc 보다 매 broader — 매 design rationale, tradeoff, alternatives, lessons-learned 의 organizational memory 로 capture. 매 2026 LLM-augmented retrieval (Backstage + RAG) 의 era 에서 매 "ask the architecture" 의 가능.
## 📖 구조화된 지식 (Synthesized Content)
소프트웨어 아키텍처 지식 관리는 복잡한 시스템을 설계하고 유지보수하는 데 있어 핵심적인 지원 활동(Supporting Activity)으로, 다음과 같은 주요 내용으로 구성됩니다.
## 매 핵심
* **지식의 탐색 및 의사소통 (Knowledge Management and Communication):**
소프트웨어 아키텍트는 고립되어 작업하지 않으며 다양한 이해관계자로부터 기능적/비기능적 요구사항과 설계 컨텍스트를 수집합니다 [1]. 디자인 패턴 검색, 프로토타이핑, 숙련된 개발자 및 아키텍트와의 상담, 유사 시스템 설계 평가, 그리고 위키 페이지 등을 통한 경험 공유 활동이 모두 지식 관리에 포함됩니다 [1]. 소프트웨어 아키텍처 설계 문제는 복잡하고 상호 의존적이므로, 설계 논리(Design Reasoning)에 지식 격차가 발생하면 잘못된 아키텍처 설계로 이어질 수 있습니다 [1].
* **설계 추론 및 의사결정 (Design Reasoning and Decision Making):**
아키텍처 설계는 의사결정의 연속입니다. 설계 결정 문제를 공식화하고, 해결 옵션을 찾으며, 결정을 내리기 전에 트레이드오프(Trade-offs)를 평가하는 지식 활동이 필수적입니다 [1]. 이는 아키텍처 요구사항 분석, 종합, 평가라는 핵심 활동의 근간이 됩니다 [1].
* **아키텍처 결정의 문서화 (Documentation & ADR):**
아키텍처 결정은 한 번 내려지면 되돌리기 어렵고, 시간이 흐를수록 그 배경과 지식이 잊혀지기 쉽습니다 [3]. 이를 방지하기 위해 '아키텍처 결정 기록(Architecture Decision Record, ADR)'이 활용됩니다 [4], [3]. ADR에는 초기 상황(Context), 결정 사항(Decision), 선택의 이유(Reason), 대안(Alternatives), 그리고 위험 및 결과(Risks and consequences)가 포함되어야 합니다 [4], [5]. 이를 통해 수개월 또는 수년이 지난 후에도 새로운 팀원, 감사자, 이해관계자가 과거의 결정을 명확히 이해하고 시스템을 진화시킬 수 있습니다 [5], [3].
### 매 knowledge types (Bosch & Jansen)
- **Application generic** — domain knowledge, tech stack rationale.
- **Application specific** — this-project decisions, constraints.
- **Tacit** — engineer brain, undocumented reasoning.
- **Explicit** — ADR, diagrams, doc.
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
아키텍처 지식을 관리하고 의사결정을 내리는 과정에는 필연적인 제약과 반대급부가 존재합니다.
### 매 SAKM activities
- Capture (ADR, retrospective, RFC).
- Share (wiki, talks, brown-bag).
- Retain (versioned repo, search index).
- Use (decision input, onboarding).
- Evolve (deprecation, supersedes link).
* **결정 지연과 분석 마비(Analysis Paralysis):** 아키텍트는 잘못된 결정을 내릴 것을 두려워하여 결정을 회피하거나 미루는 안티패턴(Anti-pattern)에 빠질 수 있습니다 [6]. 아키텍처 결정을 문서화하고 지식을 수집하는 것은 중요하지만, 불필요한 지연은 분석 마비를 초래하여 팀의 진행을 방해할 수 있습니다. 따라서 충분한 정보를 바탕으로 결정을 정당화할 수 있는 '마지막 책임 순간(Last responsible moment)'에 결정을 내리는 균형이 필요합니다 [6].
* **지식 증발(Knowledge Vaporization)과 아키텍처 침식(Architecture Erosion):** 이메일 등 파편화된 매체로만 아키텍처 결정을 소통하거나 문서화를 소홀히 하면 시스템에 대한 지식이 증발하게 됩니다 [6], [7]. 이는 시간이 지남에 따라 의도된 아키텍처와 실제 구현된 아키텍처 간의 격차가 벌어지는 '아키텍처 침식'으로 이어지며, 결과적으로 소프트웨어 성능을 저하시키고 유지보수 및 진화 비용을 크게 증가시킵니다 [7], [8].
* **품질 속성 간의 타협(Trade-offs):** 지식을 바탕으로 아키텍처 패턴을 결정할 때 "완벽한 아키텍처는 없으며 모든 결정은 타협"이라는 원칙을 수용해야 합니다 [9], [10]. 예를 들어, 극도로 안전한 암호화 접근 방식을 선택하면 성능(지연 시간)이 희생될 수 있으며, 개발 속도를 최우선으로 하면 훗날 유지보수성이 저하되는 식의 상호작용이 발생합니다 [10], [11].
### 매 응용
1. Backstage TechDocs + RAG ask-bot.
2. ADR with `supersedes` graph for decision evolution.
3. Onboarding from architecture playbook.
4. Post-incident rationale retention.
5. M&A knowledge transfer.
## 🔗 지식 연결 (Graph)
### Related Concepts
## 💻 패턴
#### [아키텍처 기록 및 문서화 도구]
- [[Architecture Decision Record (ADR)]]
- 연결 이유: 아키텍처 지식을 명시적으로 캡처하고 의사결정의 이력을 관리하는 가장 직접적인 도구입니다.
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 아키텍처 결정이 어떤 비즈니스 맥락과 기술적 대안 검토를 거쳐 내려졌는지 문서화함으로써, 향후 발생할 수 있는 시스템 진화와 지식 증발 방지 메커니즘을 깊이 이해할 수 있습니다 [4], [5], [3].
- [[Architecture Description (아키텍처 명세)]]
- 연결 이유: 아키텍처 디자인과 지식을 시각적 뷰(예: 4+1 뷰 모델)로 표준화하여 기록하는 활동입니다.
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 정적(코드 구조), 동적(실행 중 동작), 배포 뷰 등을 통해 시스템 설계를 모델링하고 이해관계자와 소통하는 방법을 파악할 수 있습니다 [12], [1].
#### [아키텍처 지식 평가 및 검증 기술]
- [[ATAM (Architecture Tradeoff Analysis Method)]]
- 연결 이유: 아키텍처 결정(지식)을 평가하고 타협점을 식별하기 위한 소프트웨어 공학의 표준 방법론입니다.
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: "사용자가 10분 내에 2배로 증가할 때"와 같은 구체적인 '시나리오'를 활용하여 아키텍처의 민감성 지점(Sensitivity points)과 위험을 도출하는 실무적 지식 검증 과정을 이해할 수 있습니다 [10], [11].
- [[Architecture Erosion (아키텍처 침식)]]
- 연결 이유: 아키텍처 지식 관리가 실패했을 때 시스템에 발생하는 구조적 퇴화 현상입니다.
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 지식 증발(Knowledge vaporization)이나 아키텍처 위반이 어떻게 시스템의 품질 저하와 기술 부채 누적으로 이어지는지 파악할 수 있습니다 [7].
### Deeper Research Questions
- 암묵적(Tacit)인 소프트웨어 아키텍처 지식을 이해관계자들의 머릿속에서 효과적으로 추출하여 ADR과 같은 명시적 지식으로 변환하기 위한 구체적인 방법론이나 프레임워크는 무엇인가?
- 프로젝트의 민첩성(Agility)을 저해하지 않으면서도, 아키텍처 결정의 근거(Rationale)와 트레이드오프를 충분히 남길 수 있는 최적의 문서화 수준(Just-enough documentation)은 어떻게 결정되는가?
- 지식 증발(Knowledge Vaporization)로 인한 아키텍처 침식(Architecture Erosion)을 조기에 탐지하기 위해 정적 코드 분석 도구나 아키텍처 적합성 검사(Conformance checks)를 어떻게 자동화할 수 있는가?
- 비즈니스 목표나 운영 환경(Context)이 급격하게 변화할 때, 과거에 기록된 아키텍처 결정(ADR)을 지속적으로 검토(Review)하고 현재의 아키텍처 구조와 동기화하는 최적의 프로세스는 무엇인가?
- 대규모 마이크로서비스(MSA)나 이벤트 기반 아키텍처(EDA) 환경에서, 분산된 팀들이 개별적으로 내리는 아키텍처 결정과 지식을 전체 조직 차원에서 어떻게 통합하고 일관되게 관리할 수 있는가?
### Practical Application Contexts
- **Implementation:** 기술적 불확실성이 존재하는 경우 프로토타입(Prototype)이나 개념 증명(Proof of concept)을 구현하여 아키텍처 아이디어를 조기에 검증하고, 여기서 얻은 실증적 지식을 바탕으로 의사결정의 위험을 최소화합니다 [1], [13], [14].
- **System Design:** 아키텍처를 설계할 때 단순히 "어떻게(How)" 구현할 것인가를 넘어 "왜(Why)" 특정 패턴과 구조를 선택했는지에 집중하며 [9], 다양한 옵션의 트레이드오프를 평가하는 논리적 추론 과정을 거칩니다 [1].
- **Operation / Maintenance:** 운영 중 장애가 발생하거나 새로운 기능 요구사항이 추가될 때, 기존에 작성된 ADR을 참고하여 과거의 설계 철학을 이해함으로써 아키텍처의 개념적 무결성(Conceptual integrity)을 훼손하지 않는 유지보수를 수행합니다 [15], [5].
- **Learning Path:** 시스템 설계자는 디자인 패턴 리서치, 타 시스템의 아키텍처 평가, 동료 전문가와의 논의 등을 통해 지속적으로 지식을 습득하고, 이를 사내 위키 등 지식 관리 시스템에 기록하여 팀 전체의 역량을 강화합니다 [1].
- **My Project Relevance:** 프로젝트 초기 단계에서 비즈니스 목표와 중요 품질 속성(성능, 확장성 등)을 정량화하여 우선순위를 매기고, 이를 바탕으로 최적의 아키텍처 패턴을 선정하는 과정을 체계적(Matrix, ATAM 등 활용)으로 밟으며 그 결과를 문서화하는 데 적용할 수 있습니다 [16], [17], [3].
### Adjacent Topics
- [[Software Architecture Recovery (소프트웨어 아키텍처 복구)]]
- 확장 방향: 아키텍처 문서가 구식이 되거나 아키텍처 침식이 심각하게 진행되었을 때, 구현된 소스 코드나 가용한 정보를 바탕으로 기존 시스템의 아키텍처 구조와 지식을 역엔지니어링하여 재구성하는 기법을 탐구할 수 있습니다 [18].
- [[Conway's Law (콘웨이의 법칙)]]
- 확장 방향: "시스템을 설계하는 조직은 그 조직의 의사소통 구조를 복제한 설계를 만들어낸다"는 인지적 제약(Cognitive constraints)을 통해, 조직 구조가 아키텍처 지식의 공유 및 의사결정 패턴에 미치는 사회 기술적(Socio-technical) 영향을 확장하여 분석할 수 있습니다 [19].
---
*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
### Backstage TechDocs site
```yaml
# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: orders-service
annotations:
backstage.io/techdocs-ref: dir:.
spec:
type: service
lifecycle: production
owner: orders-team
```
## 🤔 의사결정 기준 (Decision Criteria)
### ADR with supersedes graph
```markdown
# ADR-0042: Use Postgres
**Status:** Superseded by [ADR-0091](./0091-cockroachdb.md)
**Date:** 2026-01-15
**선택 A를 써야 할 때:**
- *(TODO)*
## Context
...
**선택 B를 써야 할 때:**
- *(TODO)*
## Decision
Postgres 16 + logical replication.
**기본값:**
> *(TODO)*
---
## ❌ 안티패턴 (Anti-Patterns)
# ADR-0091: Migrate to CockroachDB
**Status:** Accepted
**Supersedes:** [ADR-0042](./0042-postgres.md)
**Date:** 2026-05-01
```
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
### RAG over architecture corpus
```python
from langchain.vectorstores import Chroma
from langchain.embeddings import OpenAIEmbeddings
from langchain.chat_models import ChatAnthropic
docs = load_markdown_dir('./docs/architecture/')
vectorstore = Chroma.from_documents(docs, OpenAIEmbeddings())
retriever = vectorstore.as_retriever(search_kwargs={'k': 6})
llm = ChatAnthropic(model='claude-opus-4-7')
chain = create_retrieval_chain(retriever, llm)
chain.invoke({'input': 'why did we choose postgres for orders service?'})
```
### Decision retrospective template
```markdown
# Decision Retrospective: ADR-0042 (Postgres)
## Outcomes (12 months later)
- Met expected throughput: ✅
- Sharding ceiling hit: ✅ (earlier than predicted)
- Migration cost estimate: $X actual vs $Y predicted
## What we'd do differently
- Pilot CockroachDB earlier (proxy: ADR-0091 supersedes).
```
### Knowledge graph (architecture entities)
```cypher
// Neo4j architecture knowledge graph
CREATE (a:ADR {id: '0042', title: 'Postgres'})
CREATE (b:ADR {id: '0091', title: 'CockroachDB'})
CREATE (b)-[:SUPERSEDES]->(a)
CREATE (s:Service {name: 'orders'})
CREATE (s)-[:USES]->(:Tech {name: 'CockroachDB'})
CREATE (s)-[:DECIDED_BY]->(b)
```
### RFC process (lightweight)
```markdown
# RFC-0017: Move to event-sourcing for orders
**Status:** Discussion (review by 2026-06-01)
**Author:** @alice
**Stakeholders:** orders-team, platform
## Problem
...
## Proposal
...
## Alternatives
...
## Migration plan
...
```
### Architecture review board (ARB) cadence
```markdown
## ARB Charter
- Weekly 1h review slot
- ADR draft must circulate 48h pre-meeting
- Outcomes recorded in ADR + linked to RFC if applicable
- Quorum: 3/5 architects
```
## 매 결정 기준
| 상황 | Approach |
|---|---|
| Per-decision capture | ADR with supersedes link |
| Searchable corpus | Backstage + RAG |
| Cross-team knowledge | RFC process + ARB |
| Tacit → explicit | Retro + interview transcripts |
| Org-scale | Knowledge graph (Neo4j) |
**기본값**: ADR repo + Backstage TechDocs + RAG search + ARB weekly + retro every 6 months.
## 🔗 Graph
- 부모: [[Knowledge-Management]] · [[Software-Architecture]]
- 변형: [[ADR]] · [[arc42]] · [[RFC-Process]]
- 응용: [[Backstage]] · [[TechDocs]] · [[Architecture-Review-Board]]
- Adjacent: [[Software Architecture Documentation]] · [[Architecture Erosion (아키텍처 침식)]]
## 🤖 LLM 활용
**언제**: corpus indexing, ADR retrieval, "why did we...?" Q&A, gap analysis.
**언제 X**: confidential M&A pre-close — RAG isolation 필요.
## ❌ 안티패턴
- **Confluence rot**: 매 page edit 권한 too-broad → stale.
- **No supersedes link**: 매 contradict ADR 의 coexist → confusion.
- **Tacit-only**: 매 senior leave → knowledge evaporate.
## 🧪 검증 / 중복
- Verified (Bosch & Jansen "Software Architecture as a Set of Architectural Design Decisions", Spotify Backstage docs).
- 신뢰도 A.
## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — SAKM activities, Backstage+RAG, ADR supersedes, RFC/ARB |