# 원칙 (Principles)

이 원칙들은 **DeukAgentFlow**가 추구하는 "AI 엔지니어링 오케스트레이션 프로토콜"의 설계를 규정합니다.

## 1. Zero-Copy Hub-Spoke 아키텍처 (SSoT)

문서와 규칙 시스템은 단일 진실 공급원(Single Source of Truth)을 가져야 하며, 불필요한 규칙 복제를 피해야 합니다.

- **Global Hub**: `AGENTS.md`는 모든 정본 규칙을 포함합니다.
- **Local Hub**: `PROJECT_RULE.md`는 프로젝트에 특화된 규칙을 정의합니다.
- **Spoke (Zero-Copy)**: IDE별 규칙 파일은 절대 경로 포인터 역할만 수행합니다.
- **이유**: IDE마다 규칙이 복제되고 파편화되면 에이전트의 행동이 일관성을 잃고 예측 불가능해집니다.

## 2. Zero-Legacy 정책

더 이상 사용되지 않는 구조를 물리적으로 제거하여 저장소의 청결을 유지합니다.

- **이유**: 레거시 `.cursorrules`나 스테일한 서브모듈 스텁은 에이전트를 혼란스럽게 하고 컨텍스트 윈도우를 낭비합니다.
- **메커니즘**: `init` 실행 시 디프리케이션 마커와 빈 스텁을 무조건적으로 청소합니다.

## 3. Kind Src (소스 주권)

배포된 바이너리보다 로컬 개발 소스를 우선시합니다.

- **이유**: npm 등에 배포된 패키지는 로컬의 최신 규칙 업데이트를 즉시 반영하지 못할 때가 많습니다.
- **메커니즘**: Global CLI Proxy는 로컬에 `scripts/cli.mjs`가 존재할 경우 `npx` 명령을 해당 소스로 자동 위임합니다.

## 4. Smart Backup (사용자 규칙 보호)

시스템 생성 파일의 노이즈는 제거하되, 사람이 작성한 소중한 콘텐츠는 존중합니다.

- **이유**: 사용자가 생성된 파일 하단에 직접 커스텀 룰을 추가하는 경우가 많습니다.
- **메커니즘**: 순수 시스템 블록만 포함된 파일만 삭제하며, 그 외의 경우에는 `*.bak`으로 백업을 생성합니다.

## 5. 엄격한 Phase 기반 워크플로우 (TDW)

에이전트의 실행은 반드시 티켓과 Phase에 의해 제한되어야 합니다.

- **이유**: 경계가 없는 AI 에이전트는 불필요한 파일을 탐색하며 토큰을 낭비하고 범위를 벗어난 수정을 시도합니다.
- **메커니즘**: Phase 1에서 티켓을 발행하거나 기존 티켓을 선택하고 APC(Agent Permission Contract)를 채웁니다. 계획은 메인 티켓의 compact plan에만 둡니다. 진행 가능한 티켓이 없을 때는 후속 티켓을 만들기 전에 최근 git history를 분석합니다. 티켓은 스코프, 계약, 라이프사이클 체크, 검증 결과를 맡고, 계획 문구에는 진행 체크박스, 실행 로그, 명령 transcript, 완료 요약, 검증 결과를 두지 않습니다.

## 6. 변조 전 설계 (Plan Before Mutation)

상태 변화가 일어나기 전에 설계가 명시적으로 선행되어야 합니다.

- **이유**: 실제 코드나 설정 파일이 수정되기 전에 의도와 범위가 기록되어야 합니다. 티켓/계획 문서 자체는 기록물이며, 중복 티켓을 만들기 위한 승인 장벽이 아닙니다.
- **메커니즘**: 코드를 작성하기 전 티켓의 APC 블록(`[BOUNDARY]`, `[CONTRACT]`, `[PATCH PLAN]`)을 채웁니다. APC는 경계와 계약만 담습니다. 진단이나 접근 선택의 근거는 메인 티켓의 compact plan에 두고, 실행 기록의 목적지로 쓰지 않습니다.

## 7. RAG를 보완하는 문서화

안정적인 원칙과 동적인 지식은 함께 작동해야 합니다.

- **Docs**: 안정적인 운영 모델과 가정들을 설명합니다.
- **RAG (DeukAgentContext)**: 엔지니어링 메모리와 과거의 결정사항들을 온라인 MCP 계층을 통해서만 동기화합니다.
- **이유**: 로컬 파일이 진실의 원천이고, RAG는 보조 기억이며, archive가 장기 이력을 보존해야 활성 context가 꼬이지 않습니다.

## 8. 아카이브 보존

아카이브는 선택 사항이 아니라 필수 생명주기 층입니다.

- **이유**: 살아 있는 context는 작고 최신이어야 하며, 완료된 작업은 archive/knowledge로 옮겨야 활성 컨텍스트가 오염되지 않습니다.
- **메커니즘**: ticket archive와 지식 증류를 통해 완료된 작업을 active loop에서 분리하고, 결과물을 장기 참조 자료로 유지합니다.

## 9. 한/영 정합성 (Bilingual Parity)

한국어와 영어 문서는 단일 모델의 거울 쌍이어야 합니다.

- **이유**: 엔지니어링 팀은 다국어 환경인 경우가 많습니다. 문서 간 내용이 어긋나면 워크플로우 파편화가 발생합니다.