AI 에이전트(Claude Code, Codex, Cursor, Gemini CLI 등)가 프로젝트에 들어오자마자 같은 톤·같은 규칙으로 일하게 만드는 운영 매뉴얼 파일입니다. 이 수업에서는 브랜드 폴더의 brand.md, design.md를 SSoT(Single Source of Truth, 단일 진실 출처)로 두고, 그 위에 AGENTS.md / CLAUDE.md를 얹어 프로젝트 운영 체계를 만듭니다.

이번 수업에서 다루는 것

• 브랜드 폴더 구조를 만들고 brand.md / design.md의 역할을 이해합니다.
• AGENTS.md와 CLAUDE.md의 차이를 구분합니다.
• 신규 프로젝트와 기존 프로젝트에 맞는 셋업 프롬프트를 사용할 수 있습니다.
• 작업 전 가드 프롬프트와 검수 프롬프트로 drift(불일치)를 줄입니다.

1. 왜 이 구조가 필요한가

AI 에이전트는 매 세션마다 프로젝트의 맥락을 다시 읽어야 합니다. 이때 규칙이 여러 파일에 흩어져 있거나 서로 다르게 적혀 있으면, 에이전트가 매번 다른 톤·다른 디자인·다른 작업 방식으로 움직입니다.

이 구조의 핵심은 다음과 같습니다.

• brand.md → 브랜드 아이덴티티, 톤앤보이스, 금지 표현, 카피 패턴
• design.md → 컬러, 타이포, 간격, 반응형 규칙, 모션 토큰
• AGENTS.md → 모든 AI 에이전트가 공통으로 읽는 운영 매뉴얼
• CLAUDE.md → Claude Code가 새 세션을 시작할 때 자동으로 읽는 Claude 전용 진입 파일

주의: AGENTS.md / CLAUDE.md 본문에 토큰 값(HEX, 폰트명, 간격)을 직접 복붙하지 않습니다. 항상 brand.md / design.md를 SSoT로 두고, 운영 매뉴얼에는 경로 포인터와 규칙만 둡니다.

2. 개념 정리 — AGENTS.md

AGENTS.md는 도구 무관 공통 규칙 파일입니다. Claude / Codex / Cursor / Gemini CLI 어디서 켜도 같은 컨텍스트를 읽도록 합니다.

• 위치: 프로젝트 루트 AGENTS.md

  글로벌 설정은 ~/AGENTS.md

• 포함: 프로젝트 개요, 스택, 디렉토리 구조, 명령어, 컨벤션, 보호 파일 목록, 디자인 시스템 포인터, 의사결정 로그

• 원칙: 도구별 특화 내용은 빼고, 어디서 읽어도 의미가 통하는 공통 규칙만 둡니다.

3. 개념 정리 — CLAUDE.md