ttipo
2f94b6db12
지금까지 .claude 에는 "무엇을 지키는가"(rules)와 "어떻게 만드는가"(skills)만 있었고 "누가 어디까지 책임지는가"를 적을 자리가 없었다. 역할 파일은 규칙을 복사하지 않고 참조만 한다. 구현 규칙을 옮겨 적으면 스킬과 진실 공급원이 둘로 갈라져, 한쪽만 고쳐졌을 때 어느 쪽이 맞는지 알 수 없게 된다. 역할 고유의 것(담당 범위·경계·완료 기준·인계 형식)만 담는다. 리뷰어와 페르소나 둘은 frontmatter 에서 Edit/Write 를 빼 도구 수준으로 읽기 전용이다. CLAUDE.md 에는 @ import 하지 않는다 — 호출 시점에 로드되는 역할 정의다. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
에이전트 팀원 규칙
이 디렉터리는 역할(누가 무엇까지 책임지는가) 을 정의한다.
어떻게 만드는가는 .claude/skills/, 무엇을 지키는가는 .claude/rules/ 가 담당한다.
.claude/rules/ 무엇을 지키는가 (응답 포맷·에러 코드·보안 …) — 전원 공통
.claude/skills/ 어떻게 만드는가 (nestjs·vue3·flutter·docker) — 스택별
.claude/agents/ 누가 맡는가 (이 디렉터리) — 역할별
역할 목록
| 역할 | 파일 | 주 책임 | 코드 수정 |
|---|---|---|---|
| 백엔드 개발 | backend-dev.md |
backend/ API·도메인 로직 |
O |
| 프론트엔드 개발 | frontend-dev.md |
frontend/ 화면·상태·API 연동 |
O |
| 모바일 개발 | mobile-dev.md |
flutter/ 화면·상태·API 연동 |
O |
| 테스터 | tester.md |
테스트 작성·실행, 계약 테스트 유지 | O (테스트 한정) |
| 리뷰어 | reviewer.md |
공유 계약 위반·규칙 드리프트 점검 | X |
| 인프라/릴리스 | release-ops.md |
compose·env·마이그레이션·배포 | O (인프라 한정) |
| 사용자 관점 | persona-user.md |
일반 사용자 입장의 수용 기준 검토 | X |
| 관리자 관점 | persona-admin.md |
운영 담당자 입장의 수용 기준 검토 | X |
호출
"backend-dev 로 사용자 목록 API 추가해줘"
"reviewer 로 지금 변경분 검토해줘"
역할을 지정하지 않으면 평소대로 동작한다. 역할은 필요할 때 부르는 것이지, 모든 작업을 역할로 나눠야 하는 것은 아니다.
전원 공통 규칙
- 규칙을 복사하지 않는다. 역할 파일은 규칙을 참조만 한다.
응답 포맷·에러 코드·코딩 규칙의 SSOT 는
.claude/rules/와.claude/skills/다. 역할 파일에 같은 내용을 옮겨 적으면 진실 공급원이 둘로 갈라진다 (error-codes 와 같은 이유). - 경계를 넘지 않는다. 담당 범위 밖의 파일이 고쳐져야 한다면, 직접 고치지 말고 무엇이 왜 필요한지 적어 인계한다. 남의 영역을 조용히 고치면 그 영역의 규칙 검토를 건너뛰게 된다.
- 공유 계약은 단독으로 바꾸지 않는다. 응답 포맷·에러 코드·API 규약은 세 클라이언트가 함께 쓰는 계약이다. 변경이 필요하면 checklist 5절 절차를 따르고 영향 범위를 보고한다.
- 완료를 스스로 판정하지 않는다. 각 역할의 "완료 기준"에 적힌 명령을 실제로 실행하고 그 결과를 보고한다. 실행하지 않았으면 "실행하지 않음"이라고 적는다.
- 모든 산출물(주석·커밋·보고)은 한국어 (coding-common).
인계 형식
작업을 마치면 아래 4줄로 보고한다. 길게 쓰지 않는다.
- 한 일:
- 건드린 파일:
- 확인한 것: (실행한 명령과 결과. 실행 못 했으면 그 이유)
- 남은 것/인계: (다음 역할과 넘기는 이유)