Files

T

Antigravity Agent 1cfd3bbb56 docs(10_Wiki): 위키 구조 정리 — 언어 튜토리얼 카테고리 폴더 제거 + 신규 자산 동기화

Topic_CSS/Topic_HTML/Topic_JavaScript/Topic_Prompt/Topic_Comfyui 등 기존 카테고리 폴더를 정리하고,
Topic_Graphic/Dev 등 신규 산출물과 Topics 내부 세션/메모리 기록을 동기화.

2026-07-05 00:10:59 +09:00

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

AstraAI 라는 한 프로젝트 에서 추출한 결정들을 어느 프로젝트에나 쓰는 원칙으로 일반화한 것 — "AstraAI 는 X 를 쓴다" 가 아니라 "언제 X 를 쓰는가" 의 형태로, 작은 모델에게 진짜 전이 가능한 학습 데이터다.

🧠 핵심 개념 (Core concepts)

각 원칙 = (원칙 / 사용 조건 / 장점 / 단점 / 대안 / 실패 신호). AstraAI 사례는 예시 일 뿐, 규칙은 프로젝트 독립.

📖 세부 내용 (Details · 일반화된 원칙)

P1. 환경이 아키텍처를 결정한다

원칙: 동시성·저장·검증 깊이는 알고리즘이 아니라 배포 환경(자원·사용자 수·네트워크) 이 정한다.
조건: 타깃 하드웨어/규모를 알 때.
장점: 과/저설계 회피. 단점: 환경 변화 시 재평가 필요. 대안: 런타임 환경 감지 후 전략 전환.
실패 신호: "병렬이 빠르니까" 로 OOM; 서버 가정으로 로컬 앱 설계.
일반화 출처: ADR-0004 순차 디스패치 채택, 엔지니어링 트레이드오프 분석.

P2. 결정론을 바닥선으로, 비싼 것은 조건부로

원칙: 항상 동작해야 하는 기능은 저비용 결정론으로 바닥을 깔고, 비싼(LLM/네트워크) 것은 가산·조건부.
조건: 가용성·설명가능성이 중요할 때. 장점: 무중단·저지연. 단점: 결정론 한계. 대안: 항상 고비용(자원 충분 시).
실패 신호: 임베딩/외부 의존 없으면 검색이 죽음; 매 턴 LLM 검수로 느림.
출처: ADR-0007 하이브리드 검색 결정론 우선, ADR-0009 결정론 항상 LLM검증 조건부.

P3. 차이는 가장자리에서 흡수, 중심은 단일 모델

원칙: 외부(공급자/소스/디바이스)의 차이를 경계 어댑터에서 정규화하고 내부는 하나의 형태로.
조건: 이질적 외부가 여럿일 때. 장점: 호출부 단순·교체 용이. 단점: 어댑터 비용. 대안: 직접 결합(소수일 때).
실패 신호: 공급자별 분기가 코드 전체에 산재.
출처: LLM 프로바이더 추상화, Data Flow Pattern.

P4. 이력이 가치면 추가만 하라

원칙: 변경 이력이 중요하면 상태 덮어쓰기 대신 append-only 이벤트. 현재 상태는 재생.
조건: 감사/재현/되돌리기 필요. 장점: 이력 보존·내결함. 단점: 파일 증가·재생 비용. 대안: 상태 저장(마지막 값만 중요).
실패 신호: "언제 바뀌었지?" 를 알 수 없음.
출처: ADR-0001 이벤트 소싱 채택, 이벤트 소싱 스토어 패턴.

P5. 기억은 수명별로 분리하라

원칙: 수명·만료·우선순위가 다른 기억은 다른 계층/저장소에. 시한부엔 만료, 오래된 건 압축.
조건: 세션 넘는 상태가 다양할 때. 장점: 정밀 선별. 단점: 분류 비용. 대안: 단일 버퍼(단발성).
실패 신호: 옛 사실을 현재처럼 답함.
출처: ADR-0002 5계층 메모리 분리, Memory Pattern.

P6. 추상화는 두 번째 구현에서

원칙: 구현이 2개 이상이거나 테스트에 가짜가 필요할 때 인터페이스를 도입. 하나뿐이면 미루라(YAGNI).
조건: 교체/테스트 필요. 장점: 결합↓·테스트성. 단점: 과추상화 비용. 대안: 직접 구현.
실패 신호: 구현 1개짜리 인터페이스가 가득(얇은 래퍼 지옥).
출처: ADR-0006 수동 의존성주입 인터페이스 서비스, 의존성 주입과 서비스 인터페이스.

P7. 모델/외부 출력은 신뢰되지 않은 입력이다

원칙: LLM·외부 프로세스·플러그인 출력은 검증·샌드박스·승인 후 사용. JSON 은 강건 파서로.
조건: 외부 효과(파일/명령/IPC)가 있을 때. 장점: 보안·안정. 단점: 검증 코드. 대안: 화이트리스트만.
실패 신호: 모델이 시키는 대로 실행; JSON.parse 직접 호출 실패.
출처: Tool Calling Pattern, Critic Pattern, IPC Pattern.

P8. 실패는 분류하고 본류를 지켜라

원칙: 복구 가능(재시도/폴백)·불가(throw)·부가(이유 주석 후 무시)로 분류. 사용자에겐 행동 지침으로 번역.
조건: I/O·외부 의존. 장점: 복원력. 단점: 코드량. 대안: 크래시-온리.
실패 신호: 무음 빈 catch 로 실패 은폐; 부가 실패가 본류 중단.
출처: Error Handling Pattern, 에러 처리와 커스텀 에러.

P9. 흐름은 한 곳에서 읽히게, 구현은 추출

원칙: 거대 함수는 흐름 골격만 남기고 세부를 순수 모듈로. 단, 크기 상한을 정하라.
조건: 복잡한 단일 흐름. 장점: 가독성+테스트성. 단점: 경계 판단 필요. 대안: 완전 분해(흐름 분산) 또는 모놀리식.
실패 신호: 한 턴 흐름을 파악하려 파일 10개를 떠돔; 또는 5천 줄 god-class.
출처: ADR-0010 오케스트레이터 골격 모듈추출, Architecture Separation Pattern.

P10. 변하지 않은 것은 다시 계산하지 마라

원칙: 비싼 계산은 캐시하되 무효화 전략(변경 감지/버전) 을 먼저 정하라.
조건: 반복 계산·조회. 장점: 성능. 단점: stale 위험. 대안: 매번 계산.
실패 신호: 무효화 누락으로 옛 결과; 키 충돌.
출처: Caching Pattern, mtime 인덱스(TF-IDF 이중언어 스코어링).

P11. 주석은 '왜'와 '왜 다른 방법이 아닌지'를 적어라

원칙: 코드가 못 말하는 의도·제약·기각한 대안·버그 사후기록을 남겨라.
조건: 비자명한 결정/함정. 장점: 지식 전수(특히 AI 학습). 단점: 노후화 관리. 대안: ADR 문서.
실패 신호: "이게 왜 이렇지?" 를 아무도 모름; 같은 버그 재발.
출처: 코딩 컨벤션과 주석 철학, 교훈 라이브러리 Lessons Learned.

P12. 피드백 1회를 시스템 변화로 환원하라

원칙: 사용자 정정/오류를 통계로만 두지 말고 다음 동작(프롬프트·규칙)을 자동으로 바꿔라.
조건: 학습/개선 루프가 필요할 때. 장점: 자기진화. 단점: 폭주 위험(임계·상한 필요). 대안: 수동 개선.
실패 신호: 리포트만 쌓이고 행동이 안 바뀜; 1회성 노이즈로 프롬프트 오염.
출처: Intelligence 검증 레이어(correction loop), AITRAIN 검증 레이어.

⚖️ 모순 및 업데이트 (Contradictions & updates)

원칙끼리도 충돌한다(예: P6 추상화 미루기 vs P3 어댑터 도입). 충돌 시 엔지니어링 트레이드오프 분석 으로 내려가 맥락 으로 결정. 메타 원칙: 단순함 우선 · YAGNI · 환경이 결정 · 측정으로 검증.

🛠️ 적용 사례 (Applied in summary)

각 원칙은 AstraAI 의 구체 결정에서 일반화. 다른 프로젝트(웹/모바일/백엔드)에 그대로 적용 가능 — 플랫폼 개발 가이드 인덱스 의 가이드들이 이 원칙의 플랫폼별 구체화.

🔗 지식 그래프 (Knowledge Graph)

상위/루트: Topic Programming 인덱스
관련 개념: 아키텍처 휴리스틱, 엔지니어링 트레이드오프 분석, 패턴 카탈로그 인덱스, 교훈 라이브러리 Lessons Learned
참조 맥락: 작은 모델이 어떤 프로젝트를 설계하든 최상위 원칙으로 먼저 참조.

📚 출처 (Sources)

[S1] AstraAI 전체 결정의 일반화(본 위키 ADR/패턴/교훈 모음)

📝 변경 이력 (Change history)

2026-06-13: AstraAI 설계 원칙을 프로젝트 독립 형태로 일반화.

8.5 KiB Raw Blame History