Files

T

Antigravity Agent 9a135bd19d docs(10_Wiki): Topic_Business/General/Graphic/Programming을 Topics/ 하위로 이동

최상위 10_Wiki/Topic_*였던 4개 카테고리 폴더를 10_Wiki/Topics/Topic_* 로 재배치.
콘텐츠 변경 없음(순수 폴더 이동) — Topics/ 하위 나머지 폴더는 이미 지난 커밋에서
전부 정리된 상태(잔존 항목은 에이전트 운영 상태 및 사용자가 보존을 요청한
업데이트0615/무제 3.canvas 뿐).

2026-07-05 00:44:01 +09:00

5.3 KiB

Raw Blame History

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

title

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

매 응용

Backstage TechDocs + RAG ask-bot.
ADR with supersedes graph for decision evolution.
Onboarding from architecture playbook.
Post-incident rationale retention.
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

5.3 KiB Raw Blame History