문서 작성 규칙 정리

문서화

규칙 정의와 사용자 가이드 두 가지로 정리할 필요가 있다. dictionary-app/ dictionary-api 저장소는 이 둘을 파일로 분리한다 — AI가 지켜야 하는 규칙은 CLAUDE.md에, 개발자를 위한 사용법/배경 설명은 README.md에 작성한다. 아래 각 영역도 이 기준으로 어느 문서에 무엇을 남길지 정리한다.

1. 프레임워크
2. 브랜치
3. 프런트앤드
4. 백앤드
5. 템플릿 코드
6. 데이터베이스
7. 인터페이스
8. 테스트

프레임워크

1. CLAUDE.md: 기술 스택 목록(프레임워크/빌드 도구/언어/UI/린트/포맷 등)과 아키텍처 개요(레이어드 구조 등)를 짧게 정리한다.
2. 프레임워크 선택 자체는 목록형 정보라, 별도 README.md 가이드 없이 CLAUDE.md만으로 충분하다.

브랜치

1. CLAUDE.md: 브랜치 네이밍/병합 규칙({type}/{설명}, --no-ff 전용, AI 원격 push·PR 금지 등)처럼 항상 지켜야 하는 규칙을 정리한다.
2. README.md: 배포 브랜치를 분리한 이유(“master가 아니라 deploy인 이유”)와 실제 배포 흐름처럼, 배경을 알아야 이해되는 설명은 가이드 문서로 남긴다.

프런트앤드

1. CLAUDE.md: 디렉토리 구조, 컴포넌트/훅 작성 규칙처럼 코드를 작성할 때 항상 따라야 하는 규칙을 정리한다.
2. README.md: useApi/Toast/Dialog/Modal/AG Grid처럼 공통 유틸을 실제로 어떻게 호출하는지 예시 코드와 함께 사용법을 남긴다.

백앤드

1. CLAUDE.md: 코딩 컨벤션(final 명시, DTO 상속 원칙 등)처럼 리뷰 기준이 되는 규칙을 정리한다.
2. README.md: API 경로 네이밍 규칙 표, 세션/인가 동작 방식, 환경변수(jasypt 등) 설정 절차처럼 실제로 따라 하는 가이드를 남긴다.

템플릿 코드

Note

dictionary-app/dictionary-api에는 아직 템플릿 코드 문서화 사례가 없다 — 이 항목은 참조 프로젝트의 실제 관례가 아니라 이 저장소에서 새로 정의하는 항목이다.

1. CLAUDE.md: 템플릿 코드가 반드시 포함해야 하는 요소(CRUD 예시, 네이밍 규칙 준수 여부 등)를 규칙으로 정리한다.
2. README.md(또는 템플릿 코드 자체의 주석): 템플릿을 복사해서 새 기능을 만드는 절차를 가이드로 남긴다.

데이터베이스

1. CLAUDE.md: Flyway 버전 채번 정책, 테이블/컬럼/인덱스 네이밍 규칙처럼 항상 지켜야 하는 규칙을 정리한다.
2. README.md: 데이터베이스/계정 생성 DDL, 프로파일별(local/test/prod) 접속 정보처럼 최초 설정 시 따라 하는 절차를 가이드로 남긴다.

인터페이스

1. CLAUDE.md: 외부 연동 클라이언트를 interfaces 패키지에 두는 위치 규칙, 응답 포맷 정규화 원칙처럼 구현 규칙을 정리한다.
2. README.md: 연동 대상 API 소개, 인증키 신청 링크, 호출 제한처럼 외부 서비스에 대한 배경 정보를 가이드로 남긴다.

테스트

1. CLAUDE.md: 레이어별 테스트 방식(단위/슬라이스/통합)과 실행 명령을 관례로 정리한다.
2. 테스트는 규칙과 실행 방법이 함께 다뤄지는 경우가 많아, 별도 README.md 가이드 없이 CLAUDE.md에 통합해도 무방하다.