2nd/10_Wiki/Topics/Architecture/Software Architecture Knowledge Management (소프트웨어 아키텍처 지식 관리).md

---
id: wiki-2026-0508-software-architecture-knowledge-
title: Software Architecture Knowledge Management (소프트웨어 아키텍처 지식 관리)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [SAKM, Architecture Knowledge Management, AKM]
duplicate_of: none
source_trust_level: A
confidence_score: 0.85
verification_status: applied
tags: [architecture, knowledge-management, documentation, governance]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: markdown
  framework: backstage
---

# Software Architecture Knowledge Management (소프트웨어 아키텍처 지식 관리)

## 매 한 줄
> **"매 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" 의 가능.

## 매 핵심

### 매 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.

### 매 SAKM activities
- Capture (ADR, retrospective, RFC).
- Share (wiki, talks, brown-bag).
- Retain (versioned repo, search index).
- Use (decision input, onboarding).
- Evolve (deprecation, supersedes link).

### 매 응용
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.

## 💻 패턴

### 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
```

### ADR with supersedes graph
```markdown
# ADR-0042: Use Postgres
**Status:** Superseded by [ADR-0091](./0091-cockroachdb.md)
**Date:** 2026-01-15

## Context
...

## Decision
Postgres 16 + logical replication.

---

# ADR-0091: Migrate to CockroachDB
**Status:** Accepted
**Supersedes:** [ADR-0042](./0042-postgres.md)
**Date:** 2026-05-01
```

### 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 |