dotD의 마츠무라입니다.

사내에서 AI 에이전트를 전제로 한 개발 템플릿을 만들고 있습니다.

모노레포 (Monorepo) 구성의 스타터 키트에 규칙, 설계서, 테스트까지 포함하여, 프로덕트 개발을 진행하기 위한 토대를 정비하고 있습니다.

템플릿 정비의 동기

dotD는 「차례차례 새로운 가치를 창출하는 사업 창조 팜」으로서, 동시에 여러 개의 신규 사업에 임하며 연속적으로 새로운 가치를 세상에 계속해서 만들어내는 것을 내걸고 있습니다.

생성 AI (Generative AI)의 보급으로 인해, 엔지니어가 아닌 역할의 사람이라도 제안용 프로토타입을 만들거나 스스로 앱 개발을 하게 되었습니다. 하지만 어떻게 품질을 확보해 나갈 것인가라는 점에서는 아직 과제가 있습니다.

템플릿 정비의 목적은 프로덕트 개발의 품질 기준을 전사적으로 통일하는 데 있습니다.

엔지니어뿐만 아니라, 비엔지니어가 바이브 코딩 (Vibe Coding)으로 프로토타입을 만드는 상황에서도 일정 수준의 품질을 만족하는 코드가 생성되는 상태를 만드는 것이 목표입니다.

0 → 1 개발에서 프로토타이핑의 속도를 늦추지 않으면서, 본番(본격적인) 개발로 나아갈 때의 품질도 담보하기 위한 토대로서 이 템플릿을 설계하고 있습니다.

이 기사에서 다루는 내용

• CLAUDE.md / AGENTS.md / DESIGN.md의 역할 분담과 참조 체인 (Reference Chain) 설계
• 규칙 파일을 왜, 어떻게 분할하는가
• AI 스스로가 규칙을 생성·갱신한다는 전제의 설계
• 공통 / Backend / Frontend / Infra 스코프에 실제로 배치하고 있는 규칙 사례

규칙 파일의 참조 체인 설계

템플릿의 규칙 구성은 다음과 같습니다.

project-root/
├── CLAUDE.md # Claude Code용 엔트리 포인트 (Entry Point)
├── AGENTS.md # 에이전트 공통 규칙 (CLAUDE.md에서 참조)
...

포인트는 3층 참조 체인입니다.

CLAUDE.md → AGENTS.md → docs/rules/*
DESIGN.md → docs/rules/*

CLAUDE.md는 Claude Code 고유의 설정에 집중하고, 코딩 규칙은 AGENTS.md로 위임합니다. 이렇게 함으로써 Claude Code 이외의 에이전트 (Codex 등)를 사용하는 경우에도 AGENTS.md를 참조처로 지정하면 동일한 규칙이 적용됩니다.

AGENTS.md와 DESIGN.md는 각각 docs/rules/ 하위의 개별 규칙 파일에 대한 참조 링크를 가진 인덱스 (Index)입니다. 에이전트는 태스크와 관련된 규칙만을 따라가며 읽어들입니다.

왜 규칙을 하나의 파일로 합치지 않는가

CLAUDE.md에 모든 규칙을 써 내려가는 것에는 4가지 과제가 있습니다.

1. PJ(프로젝트)나 팀마다 규칙을 커스터마이징하기 어렵다

규칙은 전사 공통으로 고정할 수 있는 것들만 있는 것이 아닙니다. 프로덕트의 기술 스택, 팀의 리뷰 관점, 운용 페이즈에 따라 「지켜야 할 것」은 변합니다.

하나의 거대한 파일에 모든 것을 써 버리면, PJ 고유의 규칙을 추가하고 싶을 뿐인데 공통 규칙까지 포함하여 편집하게 됩니다. 파일을 분할해 두면 공통 규칙은 그대로 둔 채, PJ별 규칙 파일만 추가하거나 교체할 수 있습니다.

2. 규칙을 갱신하기 어렵다

개발을 진행하다 보면 「이런 방식은 그만두자」, 「이 패턴으로 통일하자」라는 판단이 매일 생겨납니다.

하나의 거대한 파일로 집약하면 AI에 의한 안전한 추가가 어려워집니다. 파일 끝에 추가하는 방식은 구조가 무너질 리스크가 있습니다. 적절한 섹션에 삽입하려면 기존 구조를 정확히 이해해야 합니다.

파일이 분할되어 있다면, 새로운 규칙을 파일 하나로 추가하고 AGENTS.md의 인덱스에 한 줄을 더하는 것만으로 대응할 수 있습니다. AI와 인간 양측 모두에게 안전하고 다루기 쉬운 구조가 됩니다.

3. 컨텍스트 윈도우 (Context Window)를 압박한다

프론트엔드 수정에서 백엔드의 API 설계 규칙까지 참조할 필요가 있는 케이스는 많지 않습니다. 모든 규칙을 하나의 파일로 합치면 태스크와 무관한 규칙까지 컨텍스트 윈도우에 들어가 토큰 (Token)을 소비합니다.

참조 체인으로 분할해 두면, 에이전트는 AGENTS.md의 인덱스를 읽고 태스크와 관련된 규칙 파일만을 선택적으로 읽어들입니다.

4. 변경 이력의 입도가 거칠어진다

규칙이 하나의 파일에 모여 있으면, git의 차이점(diff)을 통해 "무엇이 바뀌었는지" 파악하기 어려워집니다. 파일 단위로 분할되어 있다면, 커밋 로그(commit log)를 통해 규칙의 변천 과정을 추적할 수 있습니다. 설계서, 변경 경위, 의사결정 로그 등도 모두 .md 파일로 만들어 git 상에서 버전 관리(version control)함으로써, 담당자가 바뀌더라도 동일한 판단 기준으로 개발을 진행할 수 있습니다.

실제로 어떤 규칙을 배치하고 있는가

docs/rules를 다음과 같은 5가지 레이어(layer)로 나누었습니다.

• 10_principles (원칙)
• 20_domain (도메인 정의)
• 30_architecture (구조)
• 40_process (절차)
• 50_decisions (의사결정)

각 레이어 아래에는 common / frontend / backend / infra의 스코프(scope)를 설정했습니다.

각 스코프에 배치한 대표적인 규칙을 몇 가지 소개합니다.

공통: AI가 구현할 때의 행동 원칙

10_principles 레이어에서, AI 에이전트가 구현·수정·리뷰를 할 때의 공통 행동 원칙을 정의하고 있습니다.

예를 들어 다음과 같은 항목을 두고 있습니다.

• 경로 분기나 재시도 판정, 상태 코드 처리 등 결정론적(deterministic)으로 작성할 수 있는 처리는 코드로 구현하며, 모델 추론(model inference)에 맡기지 않는다.
• 기존 구현과 모순되는 두 가지 패턴을 절충하여 제3의 패턴을 늘리지 않는다.
• 변경 전에 대상 파일의 공개 API, 최근 호출자, 공유 유틸리티를 읽어 기존의 설계 의도를 파악한다.
• 비즈니스 로직이 바뀌었을 때 실패하지 않는 테스트는 "불충분"한 것으로 취급한다.
• 명명(naming)·책임 분할·에러 핸들링(error handling)은 기존 규약을 따르며, 이견이 있다면 구현 내에서 암묵적으로 분기시키지 말고 별도의 태스크(task)로 제안한다.

이것들은 특정 기술 스택에 의존하지 않으며, AI에게 맡겨 동작시킬 때 보편적으로 유효한 가드레일(guardrail)입니다.

Backend: 계층 경계와 DDD의 고정

Backend는 TypeScript / Python / Go 중 무엇을 채택하더라도, DDD(도메인 주도 설계) 기반의 계층 구조를 공통 전제로 합니다.

30_architecture/ 레이어에서 정의하고 있는 구조는 다음과 같습니다.

• domain/: Entity, Value Object, Repository Port
• usecase/: 유스케이스의 오케스트레이션(orchestration), 인가(authorization), 트랜잭션 경계
• infrastructure/: 영속화(persistence), 외부 서비스 연결
• interface/: API 입출력, 전송(transport) 사양(REST / RPC)과의 매핑

의존 방향은 interface -> usecase -> domain만 허용하며, domain은 외부 라이브러리나 전송 사양에 의존하지 않음을 명시하고 있습니다.

이와 짝을 이루는 절차 규칙이 40_process 레이어에 있으며, Backend 변경 시의 흐름을 다음과 같이 고정하고 있습니다.

• 변경 대상을 domain / usecase / infrastructure / interface로 분류
• failing test를 먼저 작성 (Red)
• 최소 구현으로 test를 통과시킴 (Green)
• test가 통과되는 상태를 유지하며 개선 (Refactor)
• pnpm lint와 해당 테스트를 실행
• interface 변경 시에는 contracts 매핑 차이 확인

"TDD(테스트 주도 개발)로 진행할 것"과 "계층 경계 위반 시 설계를 재분할할 것"까지를 절차로 상세히 적어두었기 때문에, AI가 PR(Pull Request)을 보낼 때나 인간이 리뷰할 때나 판단 기준이 일치합니다.

Frontend: UI 원칙과 접근성

Frontend에서는 시각 설계 원칙을 10_principles 레이어에 정의하고 있습니다.

• 근접·정렬·반복·대비(contrast)를 통해 정보의 시각적 계층을 명확히 한다.
• 여백과 그리드(grid)는 일관된 리듬으로 적용한다.
• 정보 구조와 레이아웃 구조를 대응시킨다.
• 시각적 계층과 정보 우선도가 역전되는 레이아웃은 금지한다.

사용성(usability)과 접근성(accessibility) 원칙도 정의하고 있습니다.

10_principles 레이어에 닐슨의 휴리스틱(Nielsen's heuristics)과 WCAG 2.1 AA를 구현 판단 기준으로 삼아 규칙화하였습니다.

이것들은 저희 디자이너가 디자인 리뷰 (Design Review)를 수행할 때 포함되는 관점들입니다.

• 시스템 상태를 항상 가시화하여 사용자가 다음 동작을 예측할 수 있도록 한다
• 텍스트 대비율(Contrast ratio)은 4.5:1 이상, 폰트 크기는 12px 이상
• 정보 전달을 색상에만 의존하지 않고 형태, 문구, 아이콘으로 보완한다
• 에러 원인이나 복구 절차를 제시하지 않는 실패 표시(Failure display)는 금지

일본어 UI 고유의 타이포그래피(Typography) 규칙도 10_principles 레이어에 정의되어 있습니다.

이 부분은 Awesome Design MD 일본어판을 참고했습니다.

• font-family는 단일 폰트 지정을 금지하며, 일본어(Wajun) · 서구권(O-bun) · generic family 순으로 폴백 체인(Fallback chain)을 정의
• 일본어 본문의 line-height는 1.5 이상 (업무용 UI는 1.5–1.6, 장문 UI는 1.7–1.9)
• word-break: break-all은 URL이나 식별자 등 예외 영역으로 한정하며, 본문에 전체 적용하는 것은 금지

프론트엔드(Frontend) 구조는 30_architecture 레이어에서 Features + Colocation 방식을 채택하고 있습니다.

'2개 이상의 루트에서 재사용되는 구현은 features로 승격한다'와 같이 추출 판단 기준까지 언어화하였습니다.

Infra: Terraform의 안전한 운영과 필수 설계 관점

인프라(Infra)는 사고의 영향이 크기 때문에, 10_principles에 강력한 제약을 원칙 규칙으로 두고 있습니다.

• 에이전트(Agent) 실행은 validate / plan까지를 표준으로 하며, apply는 인간의 리뷰 후 명시적 승인을 통해 실시 - 파괴적 변경(Destructive change)을 포함하는 차분(Diff)은 의사결정(Decision)과 세트로 관리
• 변경 제안에는 **내결함성(Fault tolerance), 가용성(Availability), 성능(Performance), 백업/복구(Backup/Restore), 보안(Security), 취약점 대책(Vulnerability mitigation), 모니터링(Monitoring), 알람 설계(Alert design)**를 반드시 포함할 것 - 모니터링 및 알람이 설정되지 않은 상태로 운영을 시작하는 것은 금지

절차 측면의 40_process에서도 위의 설계 관점을 설계 리뷰에서 명시적으로 확인합니다.

terraform validate → terraform plan을 거친 후 apply 승인으로 진행하는 흐름을 고정하고 있습니다.

'AI에게 Terraform을 맡긴다면 무엇을 반드시 지키게 할 것인가'를 원칙과 절차 양쪽에서 중복하여 정의하고 있습니다.

그렇게 함으로써 에이전트가 어느 쪽을 읽더라도 동일한 결론에 도달하도록 하고 있습니다.

요약

컨텍스트 엔지니어링(Context Engineering)을 실제 템플릿에 구현하며 얻은 배움을 정리합니다.

• 규칙 파일은 분할한다. 1개 파일당 1개의 관심사(Separation of concerns). AI 스스로 규칙을 안전하게 추가할 수 있는 구조로 만든다.
• 참조 체인(Reference chain)을 설계한다. CLAUDE.md → AGENTS.md → docs/rules/* 의 3층 구조로, 태스크에 필요한 컨텍스트만 선택적으로 읽어 들인다.
• 공통 / Backend / Frontend / Infra 스코프(Scope)로 나누어 작성한다. 공통 규칙은 기술 스택에 의존하지 않는 행동 원칙을, 스코프별 규칙은 계층 경계, UI 원칙, IaC 안전 운영과 같이 성격이 다른 가드레일(Guardrail)을 배치한다.

디자인 시스템(Design System)을 컨텍스트 자산으로서 템플릿에 포함하는 설계는 향후 도입할 예정입니다. 토큰(Token)이나 컴포넌트 카탈로그(Component catalog)를 어떻게 참조시키고 어떻게 검증할지는 별도의 기사에서 다시 다루겠습니다.