배경
우리 팀 프론트엔드는 3명인데, AI 코딩 도구가 각각 다르다.
같은 레포에서 작업하는데 도구가 다르면, AI한테 프로젝트 컨텍스트를 어떻게 공유할지가 문제였다. Claude Code는 CLAUDE.md를 읽고, Codex는 AGENTS.md를 읽는다. 각각 따로 관리하면 내용이 어긋날 수밖에 없다.
AGENTS.md + CLAUDE.md 패턴
AGENTS.md를 공유 소스로 두고, CLAUDE.md는 이걸 참조만 한다.
# CLAUDE.md
@AGENTS.md이렇게 하면:
- Codex →
AGENTS.md직접 읽음 - Claude Code →
CLAUDE.md열면@AGENTS.md참조로 같은 내용을 읽음 - 관리 포인트는
AGENTS.md하나
Claude Code 전용 설정이 필요하면CLAUDE.md에@AGENTS.md아래에 추가하면 된다.
AGENTS.md
# 런치캐치 (Lunch Catch)
위치 기반 점심 쿠폰 할인 서비스. 직장인이 주변 가게 쿠폰을
스와이프로 찜하고, 11:00 선착순 오픈에 발급받는 구조.
## 기술 스택
- React 19 + Vite 8 + TypeScript
- Tailwind CSS
- Storybook
- ESLint / Prettier / Husky
## 현재 스프린트
- Sprint 2 (9/28 ~ 10/2): UI + mock 데이터 구현 (API 연동 없음)
## 참고 문서
- docs/requirements-user.md — 사용자(직장인) 요구사항 명세서
- docs/requirements-owner.md — 점주 요구사항 명세서
- docs/requirements-admin.md — 관리자 요구사항 명세서
- docs/requirements-common.md — 공통/시스템 요구사항
- docs/folder-structure.md — 폴더 구조
- docs/conventions.md — 코딩/커밋/브랜치 규칙
## 핵심 규칙
- "가게" 사용 ("식당" X)
- 서빙 시간대: 10:00~12:59
- 쿠폰 발급은 찜 목록에서만 (피드 카드에 발급 버튼 없음)
- 11:00 선착순 오픈, 10:50 알림
- 브랜드 컬러: #F56B20
## 담당
| 역할 | 담당자 | 도구 |
|------|--------|------|
| FE-사용자 | 서지현 | Claude Code |
| FE-점주 | 이규태 | Codex |
| FE-관리자 | 고유정 | Claude Code |AI 도구가 코딩할 때 이 파일을 먼저 읽으면, 프로젝트 맥락을 잡고 규칙에 맞는 코드를 생성할 수 있다. 예를 들어 "식당"이라고 쓸 수 있는 곳에서 "가게"로 통일한다든지, 브랜드 컬러를 자동으로 맞춘다든지.
docs/ 폴더 구조
요구사항 명세서 + 프로젝트 규칙 문서를 docs/ 폴더에 정리했다.
lc-frontend/
├── AGENTS.md
├── CLAUDE.md
└── docs/
├── requirements-user.md # 사용자 요구사항 (32개)
├── requirements-owner.md # 점주 요구사항 (26개)
├── requirements-admin.md # 관리자 요구사항 (27개)
├── requirements-common.md # 공통/시스템 요구사항 (10개)
├── folder-structure.md # 폴더 구조
└── conventions.md # 코딩/커밋/브랜치 규칙요구사항을 역할별로 분리한 이유
원래 요구사항 명세서는 하나의 큰 파일이었다.
(사용자/점주/관리자/공통 전부 합쳐서 약 95개 기능).
문제
- AI 도구가 사용자 피드 만드는데 관리자 대시보드 스펙까지 읽음
- 파일이 너무 길어서 컨텍스트 낭비
역할별로 나누니까 각 담당자의 AI가 자기 파트만 집중해서 읽을 수 있다.
conventions.md
커밋 컨벤션, 브랜치 전략, 코딩 규칙은 AGENTS.md에 넣을 수도 있었지만, 내용이 길어지면 핵심 규칙이 묻힌다. AGENTS.md는 짧고 핵심만, 상세 규칙은 docs/에 분리하고 참조 경로만 남기는 게 깔끔했다.
주요 규칙만 정리하면:
| 항목 | 규칙 |
|---|---|
| 커밋 타입 | feat / fix / docs / style / refactor / test / chore / design / rename / remove |
| 커밋 제목 | 한국어, 60자 이내, 마침표 없음 |
| 브랜치 | main(배포) → develop(통합) → feature/*(기능) |
| 컴포넌트 | 함수형 + arrow function |
| 스타일 | Tailwind 유틸리티 클래스 |
| 상태관리 | useState / useContext만 사용 |
느낀 점
이전 프로젝트(요고다)에서는 프론트/백 혼자 다 했기 때문에, AI한테 맥락을 줄 때도 그냥 프롬프트에 직접 넣어줬다. "너는 프론트 개발자야", "너는 백엔드 개발자야" 하면서 각각 역할을 나눠 소통시키는 방식이었고, 프로젝트 정보를 md 파일로 정리해서 코드에 넣지는 않았다.
이번에는 팀 프로젝트고 도구도 다르다 보니, 공통되는 규칙이나 맥락을 md 파일로 관리하는 게 훨씬 효율적이겠다는 생각이 들었다. 한 번 정리해두면 팀원 누가 어떤 도구를 쓰든 같은 맥락에서 출발할 수 있으니까.
이번 프로젝트에서는 AI를 좀 더 다양하게, 제대로 활용해보려고 한다.
