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

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

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

# 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

# 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

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

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

// 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)

# 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

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

• 부모: Software-Architecture
• 변형: ADR · arc42 · RFC-Process
• 응용: Backstage · TechDocs
• 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