SOP: 계층형 도메인 아키텍처(Layered Domain Architecture)

에이전트(agent)가 경계를 계속 위반하거나, 계층 간에 로직을 중복 작성하거나, 몇 번의 세션 후에 검토하기 어려운 코드를 생성할 때 이 표준 작업 절차(SOP)를 사용하십시오.

계층형 아키텍처(layered architecture)란 코드베이스를 역할별 계층으로 분리하고, 각 계층 간의 의존성 방향을 명시적으로 정해 에이전트가 구조를 조용히 훼손하지 않고 빠르게 작업할 수 있게 하는 설계 원칙입니다.

목표

도메인 경계를 명시적으로 만들어 에이전트가 구조를 조용히 훼손하지 않고 빠르게 이동할 수 있도록 합니다.

목표 모델

비즈니스 도메인 내에서는 다음과 같은 방향성 흐름을 선호하십시오.

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

횡단 관심사(cross-cutting concern)는 명시적인 공급자(provider) 또는 어댑터(adapter)를 통해 진입해야 합니다. 공유 유틸리티는 도메인 외부에 위치하며, 도메인 로직을 축적해서는 안 됩니다.

설정 체크리스트

• ARCHITECTURE.md에 현재 도메인들을 정의한다.
• ARCHITECTURE.md에 허용된 의존성 방향을 기록한다.
• auth, 텔레메트리(telemetry), 외부 API 등 횡단 관심사 인터페이스를 기록한다.
• 현재 가장 문제가 되는 경계 위반에 대한 짧은 노트를 하나 추가한다.
• 린트, 테스트, 또는 스크립트로 기계적으로 강제할 항목을 결정한다.

실행 절차

1. 구현 스타일에 손을 대기 전에 코드베이스를 도메인으로 매핑한다.
2. 각 도메인에 대해 허용된 계층 시퀀스를 확인한다.
3. 모든 횡단 관심사를 식별하고 공급자 또는 어댑터를 통해 라우팅한다.
4. 애매한 공유 로직을 소유 도메인으로 이동하거나 진정한 범용 유틸리티로 분리한다.
5. 규칙을 ARCHITECTURE.md에 문서화한다.
6. 가장 비용이 큰 위반 사항에 대해 하나의 실행 가능한 가드레일(guardrail)을 추가한다.
7. 변경 후 품질 점수를 업데이트한다.

완료 정의

• 새로운 에이전트가 어떤 계층이 변경을 소유하는지 파악할 수 있다.
• UI 코드가 더 이상 저장소나 외부 사이드 이펙트에 직접 접근하지 않는다.
• 횡단 관심사는 명명된 진입점을 갖는다.
• 적어도 하나의 중요한 경계가 기계적으로 강제된다.

업데이트해야 할 저장소 산출물

• ARCHITECTURE.md
• docs/QUALITY_SCORE.md
• docs/design-docs/ — 근거가 변경된 경우
• docs/PLANS.md 또는 활성 실행 계획(execution plan)