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

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

10_Wiki/Topic_Programming/Generalized_Principles/프로젝트_독립_설계_원칙.md

@@ -0,0 +1,120 @@
+---
+id: project-independent-design-principles
+title: "프로젝트 독립 설계 원칙"
+category: "Software_Engineering"
+status: "draft"
+verification_status: "applied"
+canonical_id: ""
+aliases: ["design principles", "설계 원칙", "transferable principles", "project-independent knowledge", "엔지니어링 원칙"]
+duplicate_of: ""
+source_trust_level: "A"
+confidence_score: 0.9
+created_at: 2026-06-13
+updated_at: 2026-06-13
+review_reason: ""
+merge_history: []
+tags: ["principles", "engineering", "transferable", "design", "platform-independent"]
+raw_sources: ["AstraAI 전체 분석의 일반화", "본 위키 ADR/패턴/교훈 모음"]
+applied_in: ["AstraAI"]
+github_commit: ""
+---
+
+# [[프로젝트 독립 설계 원칙]]
+
+## 🎯 한 줄 통찰 (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 설계 원칙을 프로젝트 독립 형태로 일반화.