코딩 에이전트 DESIGN.md란?

Context

코딩 에이전트가 코드 생성 시 도메인 계층과 HTTP 계층의 경계를 파괴하거나 설계 의도를 무시하는 문제 발생. 에이전트가 팀의 암묵적 합의나 과거의 설계 결정 사항을 인지하지 못해 발생하는 아키텍처 부패 위험 존재.

Technical Solution

• 저장소 루트에 설계 의도와 제약 사항을 명시한 DESIGN.md 파일을 구축하여 에이전트의 컨텍스트로 제공
• HTTP 핸들러의 DB 직접 접근 금지 및 Outbox 패턴을 통한 게이트웨이 호출 강제 등 구체적 불변 조건 정의
• Account.post_entry()와 같은 단일 쓰기 경로(Single Write Path)를 명시하여 데이터 불일치 사고 방지
• OpenAPI 사양을 Single Source of Truth로 지정하여 API 계약 준수 및 임의 타입 수정 차단
• AGENTS.md(운영 지침)와 CLAUDE.md(도구 지침)를 분리하고 DESIGN.md를 참조하게 하여 컨텍스트 밀도 최적화
• 거부된 대안(Rejected Alternatives) 섹션을 통해 과거 실패 사례의 재도입을 원천 차단