wiki: Topic_Blog 신규 문서 일괄 추가 + ASTRA 성장 자산 동기화
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,91 @@
|
||||
---
|
||||
id: architecture-heuristics
|
||||
title: "아키텍처 휴리스틱"
|
||||
category: "Software_Engineering"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["architecture heuristics", "결정 규칙", "언제 무엇을 쓰나", "design heuristics", "의사결정 규칙"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.89
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["heuristics", "decision-rules", "architecture", "engineering", "connectai"]
|
||||
raw_sources: ["ConnectAI 전체 분석", "본 위키 ADR/트레이드오프 모음"]
|
||||
applied_in: ["ConnectAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[아키텍처 휴리스틱]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
좋은 설계자는 매번 0부터 고민하지 않고 *결정 규칙(휴리스틱)* 을 적용한다 — "언제 X 를 만들고, 언제 만들지 않는가" 를 명시한 규칙 모음은 작은 모델에게 가장 실용적인 설계 지능이다.
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
- 휴리스틱 = "조건 → 권장 선택" 의 빠른 판단 규칙. 절대 법칙이 아니라 *기본값*.
|
||||
- ConnectAI 의 실제 결정에서 역추출.
|
||||
|
||||
## 📖 세부 내용 (Details · 결정 규칙)
|
||||
|
||||
### 새 서비스(클래스/모듈)를 언제 만드나
|
||||
- **만든다:** 명확한 단일 책임 + 다른 곳에서 재사용 + 교체/테스트 필요 + 외부 효과(I/O·API) 캡슐화. → 인터페이스로 추상화([[의존성 주입과 서비스 인터페이스]]).
|
||||
- **안 만든다:** 한 곳에서만 쓰는 3줄 로직, 상태 없는 순수 변환(그냥 함수), "미래에 필요할지도" (YAGNI).
|
||||
|
||||
### 언제 이벤트(append-only)를 쓰나
|
||||
- **쓴다:** 변경 *이력 자체가 가치*, 감사/재현 필요, 추가만 하고 수정 드뭄, 여러 소비자가 같은 사실을 다르게 투영.
|
||||
- **안 쓴다:** 마지막 값만 중요, 빈번한 in-place 수정, 복잡 조인 쿼리 중심 → 상태 저장/DB.
|
||||
|
||||
### 언제 큐(동시성 제한)를 쓰나
|
||||
- **쓴다:** 대량 작업이 자원(메모리/IO/소켓)을 폭주시킬 수 있을 때, 처리량을 일정하게.
|
||||
- **안 쓴다:** 작업이 소수거나 이미 락으로 직렬화될 때(중복 제어 불필요).
|
||||
|
||||
### 언제 락을 쓰나
|
||||
- **쓴다:** 같은 공유 자원(파일/세션)에 read-modify-write 가 동시에 일어날 수 있을 때.
|
||||
- **안 쓴다:** 불변 데이터, 단일 소유자, append-only 단일 프로세스.
|
||||
|
||||
### 언제 메모리 타입을 나누나
|
||||
- **나눈다:** 수명/만료/우선순위/검색 방식이 다른 기억이 섞일 때([[5계층 메모리 시스템]]).
|
||||
- **안 나눈다:** 단발성 도구(기억 불필요), 또는 전부 같은 정책이면 단일 버퍼.
|
||||
|
||||
### 언제 에이전트를 만드나 / 만들지 않나
|
||||
- **만든다:** 진짜 독립적 전문성 + 산출물이 명확히 분리 + 자원이 여러 모델/순차를 감당.
|
||||
- **만들지 않는다:** 단일 작성자가 역할만 바꿔도 되는 작업, hop 에서 원본 손실 위험, 자원이 빠듯할 때([[ADR-0003 단일작성자 다중역할 멀티에이전트]]). **기본값은 "에이전트를 늘리지 말 것".**
|
||||
|
||||
### 언제 상태를 영속화하나 / 휘발로 두나
|
||||
- **영속:** 세션을 넘어 필요(사용자 선호, 프로젝트 결정, 학습 케이스), 투명성 필요.
|
||||
- **휘발:** 현재 턴/세션 한정(단기 버퍼), 재계산이 싼 파생값, 민감해서 남기면 안 되는 것.
|
||||
|
||||
### 언제 추상화(인터페이스)를 도입하나
|
||||
- **도입:** 구현이 2개 이상이거나 곧 생김(로컬/클라우드 엔진), 테스트에 가짜가 필요(LLM 호출).
|
||||
- **안 함:** 구현이 하나뿐이고 변할 조짐 없음(과추상화 = 비용).
|
||||
|
||||
### 언제 결정론 vs LLM 을 쓰나
|
||||
- **결정론:** 매 턴 돌릴 저비용 신호(정규식·카운트·점수). latency 0 이 중요할 때.
|
||||
- **LLM:** 의미 판단이 필요하고, 결정론 신호가 위험을 표시했을 때만(조건부)([[ADR-0009 결정론 항상 LLM검증 조건부]]).
|
||||
|
||||
### 언제 동기 vs 비동기/병렬을 쓰나
|
||||
- **병렬:** 독립 작업 + 자원 여유. 의존 없으면 `Promise.all`.
|
||||
- **순차:** 자원 제약(모델 상주), 출력이 다음 입력(peer-context), 데드락 위험.
|
||||
|
||||
### 파일 분리/추출 기준
|
||||
- 한 파일이 한 화면을 크게 넘고 *여러 책임* 을 가지면 추출. 단, *흐름 골격* 은 한 곳에 남긴다([[ADR-0010 오케스트레이터 골격 모듈추출]]).
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
휴리스틱은 *기본값* 이지 법칙이 아니다. 충돌하면 [[엔지니어링 트레이드오프 분석]] 으로 내려가 맥락(자원·규모·팀)에 맞춰 판단하라. 가장 강한 메타 규칙: **YAGNI(필요해질 때 만들어라) + 단순함 우선 + 환경이 동시성·저장·검증을 결정한다.**
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
각 규칙은 ConnectAI 의 실제 ADR 결정과 1:1 대응. 신규 기능 설계 시 이 목록을 먼저 훑는다.
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[ConnectAI 아키텍처 개요]]
|
||||
- **관련 개념:** [[엔지니어링 트레이드오프 분석]], [[안티패턴 카탈로그]], [[리팩토링 플레이북]], [[프로젝트 독립 설계 원칙]]
|
||||
- **참조 맥락:** 로컬 LLM 이 "새 것을 만들지 말지" 를 빠르게 판단할 때 1차 규칙으로 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] ConnectAI 전체 ADR/서브시스템 결정의 역추출(본 위키 Engineering_Intelligence 모음)
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: ConnectAI 결정 규칙 추출 초안.
|
||||
Reference in New Issue
Block a user