Files

T

Antigravity Agent e2c5471046 wiki: Topic_Blog 신규 문서 일괄 추가 + ASTRA 성장 자산 동기화

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-16 09:55:38 +09:00

5.5 KiB

Raw Blame History

id, title, category, status, verification_status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, created_at, updated_at, review_reason, merge_history, tags, raw_sources, applied_in, github_commit

title

아키텍처 휴리스틱

🎯 한 줄 통찰 (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 결정 규칙 추출 초안.

5.5 KiB Raw Blame History