지금까지 .claude 에는 "무엇을 지키는가"(rules)와 "어떻게 만드는가"(skills)만 있었고
"누가 어디까지 책임지는가"를 적을 자리가 없었다.
역할 파일은 규칙을 복사하지 않고 참조만 한다. 구현 규칙을 옮겨 적으면 스킬과
진실 공급원이 둘로 갈라져, 한쪽만 고쳐졌을 때 어느 쪽이 맞는지 알 수 없게 된다.
역할 고유의 것(담당 범위·경계·완료 기준·인계 형식)만 담는다.
리뷰어와 페르소나 둘은 frontmatter 에서 Edit/Write 를 빼 도구 수준으로 읽기 전용이다.
CLAUDE.md 에는 @ import 하지 않는다 — 호출 시점에 로드되는 역할 정의다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
규칙과 구현이 어긋나 있던 부분을 바로잡고, 작업하며 발견한 함정을 기록한다.
- 스킬 문서의 "기본 제공 골격" 표를 실제 파일 목록과 일치시킴
- 커밋 전 체크리스트에 테스트 실행·에러 코드 동기화 절차 추가
- 커밋 규칙에 scope·브랜치 전략·PR 규칙 보강
- 새 규칙 파일(api-design, logging)을 CLAUDE.md import 목록에 등록하고,
규칙 추가 시 등록이 필수라는 메타 규칙 명시
- README 를 현재 구조에 맞게 갱신 (traceId·페이지네이션·에러 코드 SSOT·로컬 개발 명령)
작업 중 실제로 겪은 함정들을 규칙으로 남긴다:
- Windows 에서 npm install 하면 Linux 전용 optional 의존성이 lock 에서 잘려
Docker 의 npm ci 가 실패한다 → 의존성 변경은 컨테이너 안에서 수행
- --build 만으로는 node_modules 익명 볼륨이 갱신되지 않아
새 패키지가 컨테이너에 반영되지 않는다 → --renew-anon-volumes 필요
- compose 는 미정의 변수를 빈 문자열로 주입해 Number('')===0 함정이 생긴다
- dev 는 PID 1 이 npm 이라 graceful shutdown 확인은 운영 이미지로 해야 한다
- Redis 는 컨테이너만 떠 있고 사용처가 없다 — 확장 지점임을 명시
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- 슬래시 커맨드(nestjs/vue3/flutter)를 정식 스킬(.claude/skills)로 전환하고
docker 스킬을 신설(루트 command.md 이관)
- 공통 규칙을 .claude/rules 로 모듈화(coding-common·response-format·error-codes·
git-convention·security·env-structure·testing·checklist)하고 CLAUDE.md 에서 @import
- 파일·식별자 네이밍 규약, 테스트 규칙 추가
- .claude/settings.json(권한·환경) 추가
- CLAUDE.md·README.md 참조 갱신, 단독 실행(non-Docker) 안내 정리
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ttipo