ARCHITECTURE.md

이 파일은 시스템의 최상위 지도입니다. 간결하게 유지하고 필요할 때 더 깊은 문서를 가리키도록 합니다.

아키텍처 문서는 에이전트(agent)가 코드를 변경하기 전에 읽어야 할 시스템 지도 역할을 합니다. 도메인 경계, 계층 모델, 의존성 규칙을 한 곳에 명시함으로써 에이전트가 아드혹(ad-hoc) 아키텍처를 만들지 않도록 방지합니다.

시스템 형태

제품: [제품명으로 교체]
주요 사용자 워크플로우: [주요 워크플로우로 교체]
런타임 표면: [desktop / web / cli / services / workers]
제품 동작의 진실 원천(source of truth): docs/product-specs/

도메인 지도

도메인	목적	주요 진입점	관련 명세
`[domain-a]`	`[소유하는 것]`	`[모듈 / 라우트 / 명령어]`	`[명세 경로]`
`[domain-b]`	`[소유하는 것]`	`[모듈 / 라우트 / 명령어]`	`[명세 경로]`

계층 모델

에이전트가 즉흥적인 아키텍처를 발명하지 않도록 고정된 방향성 모델을 사용한다.

Types -> Config -> Repo -> Service -> Runtime -> UI

횡단 관심사(cross-cutting concern)는 계층을 직접 가로지르는 대신 명시적인 공급자(provider) 또는 어댑터(adapter) 경계를 통해 진입해야 합니다.

의존성 하드 규칙

하위 계층은 상위 계층에 의존해서는 안 된다.
UI는 런타임 또는 서비스 계약을 우회해서는 안 된다.
데이터 접근은 저장소(repository) 또는 동등한 어댑터를 통해 진입해야 한다.
공유 유틸리티는 범용으로 유지하며 도메인 로직을 축적해서는 안 된다.
새로운 의존성은 일치하는 계획 또는 설계 문서에서 정당화되어야 한다.

횡단 관심사 인터페이스

관심사	승인된 경계	비고
로깅 및 트레이싱	`[공급자 / 유틸리티 경로]`	`[구조화만 허용, 임의 콘솔 사용 금지]`
인증(Auth)	`[공급자 경로]`	`[토큰/세션 규칙]`
외부 API	`[클라이언트 또는 공급자 경로]`	`[속도 제한 / 재시도 지침]`
기능 플래그	`[플래그 경계]`	`[소유권]`

현재 핫스팟

[에이전트가 안전하게 변경하기 가장 어려운 영역]
[경계가 약하거나 테스트가 취약한 영역]

변경 체크리스트

아키텍처 관련 코드를 수정할 때:

도메인 지도 또는 허용된 경계가 변경된 경우 이 파일을 업데이트한다.
근거가 변경된 경우 docs/design-docs/의 관련 설계 문서(design doc)를 업데이트한다.
규칙이 기계적으로 강제되어야 한다면 실행 가능한 검사를 추가하거나 업데이트한다.