결정으로 배우는 아키텍처.

설계 원칙 정리

• 되돌릴 수 없는 행동의 선행조건은 프롬프트 지시가 아니라 코드의 게이트로 강제한다 — 모델의 준수에 안전을 의존하지 않는다.
• 환불 같은 행동의 대상은 모델이 대화에서 뽑은 이름이 아니라 검증 단계가 돌려준 확정 식별자로 지목하고, 도구 스키마가 애매한 입력을 처음부터 거부하게 한다.
• 에스컬레이션은 대화를 통째로 던지거나 끊는 것이 아니라 확정 사실·시도·사유·미해결 질문을 정형화해 넘기는 인계다 — 사람이 판단에만 집중하도록 맥락을 구조화한다.
• 본인 확인·환불 완료 같은 권위 있는 사실은 대화의 기억이 아니라 그 밖의 상태에 두고 게이트가 매번 다시 읽으며, 되돌리기 어려운 도구는 멱등하게 설계해 이중 실행을 원천 차단한다.

설계 원칙 정리

• 분해는 병렬 이득과 조율 비용의 균형입니다 — 서로 겹치지 않는 자기완결 단위로, 범위와 산출 형식을 명시해 나눕니다.
• 서브에이전트는 코디네이터의 기억을 공유하지 않습니다 — 필요한 컨텍스트는 과제에 맞게 추려 명시적으로 전달해야 합니다.
• 합성은 출처가 사라지기 쉬운 지점입니다 — 주장과 근거의 연결을 반환 구조에서부터 유지해야 역추적이 살아 있습니다.
• 에러는 구조로 전파돼야 합니다 — 실패를 삼키지도 지어내지도 않고, 확보분은 살리고 공백은 정직하게 드러냅니다.

설계 원칙 정리

• 대규모 코드베이스는 단일 프롬프트로 삼키지 말고, 파일별 1차 리뷰와 파일 간 상호작용을 보는 통합 패스로 책임을 나눈 다중패스로 설계한다.
• 리뷰 인스턴스는 서로 독립시켜 문맥 오염과 편향을 차단하고, 통합 패스에는 원문 누적이 아니라 필요한 요약만 전달한다.
• CI 자동화의 핵심은 비대화형 실행과 사전 정의 스키마의 구조화 출력 — 게이트가 파싱할 수 있어야 리뷰가 판정으로 이어진다.
• 일관성은 모델의 성실함이 아니라 명시적 리뷰 기준에서 나온다 — 검사 항목·심각도 정의·무시 대상을 고정해 모든 인스턴스에 동일 적용한다.

설계 원칙 정리

• 구조화 출력에서 '값 없음'은 항목 생략이 아니라 nullable로 명시한다 — 모든 항목을 required로 두고 null을 허용해야 부재와 미발견을 지어냄 없이 구분할 수 있다.
• tool_use는 타입 준수는 보장하지만 값의 정합성은 보장하지 않는다 — 결정적 검증과, 실패 사유를 되돌려 재요청하는 상한 있는 재시도 루프를 애플리케이션 층에서 설계한다.
• 즉시 응답이 필요 없고 대량이 한꺼번에 몰리는 작업은 배치 API가 정답이다 — 비용·처리량 이점을 얻되, 결과 순서 미보장은 custom_id 매칭으로 설계상 해결한다.
• 사람 검토는 위험 신호에 정렬한다 — 모델 신뢰도·검증 실패·핵심 값 부재를 기준으로 애매한 건만 라우팅해, 자동화의 처리량과 사람 판단의 안전을 함께 얻는다.

설계 원칙 정리

• 도구 선택 신뢰성의 첫 지렛대는 설명 문구다 — 설명은 '무엇을 하는가'가 아니라 '언제·어떤 입력·어떤 출력으로 다른가'로 도구들을 구별해야 한다.
• 도구 과잉은 국면·역할별 분할 노출로, 위험한 실행은 범위 격리와 tool_choice 게이트로 다룬다 — 노출 목록과 tool_choice가 신뢰성·안전의 두 손잡이다.
• 도구는 '행동', 리소스는 '읽기 전용 맥락'이다 — 자주 바뀌지 않는 참조 데이터는 도구 호출이 아니라 MCP 리소스로 모델에 붙인다.
• 실패 응답은 모델을 위한 인터페이스다 — 오류 코드·원인·다음 행동을 담아 실패를 명시해야 모델이 반복이나 환각 없이 복구한다.

설계 원칙 정리

• 강제가 필요한 규칙은 하위 계층이 덮어쓸 수 없는 관리형 정책 계층에, 공유가 필요한 관례는 저장소에 커밋되는 프로젝트 계층에 — 규칙의 성격에 맞는 계층이 소유한다.
• 경로 규칙에서 별표 하나는 한 단계를, 별표 둘은 중첩 전체를 잡으며 deny는 언제나 allow를 이긴다 — 비밀 보호는 안내가 아니라 권한 계층에서 강제한다.
• 읽기 위주의 대규모 탐색은 격리된 포크(서브에이전트) 컨텍스트로 분리하고 정제된 결과만 되돌려받아, 본 작업 컨텍스트를 가볍게 유지한다.
• 플랜 모드는 파급이 큰 구조 변경을 위한 실행 전 검토 관문이고 직접 실행은 위험이 낮은 기계적 편집의 몫이다 — 실행 방식은 속도 취향이 아니라 파급 범위에 맞춘다.