LLM 에이전트 협업을 위한 파일 기반 상태 관리 설계

.claude/
├── agents/          # 에이전트 페르소나 및 역할 정의
├── tasks/           # 작업 단위 추적 및 결과 기록
├── instructions/    # 협업 규칙, 컨벤션, 공통 지침
└── memories/        # 프로젝트 공유 맥락 및 장기 기억

agents/
├── orchestrator.md     # 전체 작업 조율 에이전트
├── frontend.md         # 프론트엔드 전담 에이전트
├── backend.md          # 백엔드 전담 에이전트
└── reviewer.md         # 코드 리뷰 전담 에이전트

tasks/
├── 20250410-TODO-001-api-endpoint-design.md
├── 20250410-IN_PROGRESS-002-user-auth.md
└── 20250410-DONE-003-db-schema.md

instructions/
├── conventions.md      # 파일 작성 규칙, 명명 규칙
├── domain-glossary.md  # 프로젝트 도메인 용어 사전
└── tech-stack.md       # 기술 스택 및 의존성 정의

memories/
├── project-context.md      # 프로젝트 배경 및 목표
├── decisions-log.md        # 주요 기술 결정 이력
└── known-issues.md         # 알려진 문제 및 주의사항

# 생성
tasks/20250410-TODO-005-payment-integration.md

# 작업 시작 후 즉시 변경
tasks/20250410-IN_PROGRESS-005-payment-integration.md

# 완료 후 변경
tasks/20250410-DONE-005-payment-integration.md

# {에이전트 이름}

## 역할
이 에이전트의 담당 영역과 주요 책임을 한 문장으로 기술한다.

## 전문 영역
- 구체적인 전문 기술 또는 도메인 1
- 구체적인 전문 기술 또는 도메인 2

## 행동 원칙
1. 작업 시작 전 반드시 `tasks/`와 `instructions/conventions.md`를 확인한다.
2. 작업 점유 시 파일명을 즉시 `IN_PROGRESS`로 변경한다.
3. 완료 후 결과물 경로와 요약을 반드시 파일에 기록한다.
4. 다른 에이전트의 `IN_PROGRESS` 파일은 수정하지 않는다.

## 소통 방식
- 결과물을 남길 위치: `tasks/{작업ID}-DONE-...md`
- 질문이나 블로킹 이슈: 해당 task 파일의 `이슈` 섹션에 기록

---
id: {작업ID}                          # 예: 005
status: TODO | IN_PROGRESS | REVIEW | DONE
assignee: {담당 에이전트명}              # 예: backend
created_at: YYYY-MM-DD HH:MM
updated_at: YYYY-MM-DD HH:MM
priority: HIGH | MEDIUM | LOW
depends_on: [{선행 작업ID}, ...]        # 없으면 빈 배열

---

# {작업 제목}

## 목표
이 작업이 달성해야 할 구체적인 결과를 기술한다.

## 세부 요구사항
- 요구사항 항목 1
- 요구사항 항목 2

## 진행 로그
- [ ] 세부 작업 1
- [ ] 세부 작업 2
- [ ] 세부 작업 3

## 결과물
<!-- 완료 시 작성 -->
- 산출물 경로: `src/...`
- 변경 요약:

## 이슈
<!-- 블로킹 이슈 또는 다른 에이전트에게 전달할 내용 -->

## 후속 작업 제안
<!-- 이 작업 완료 후 생성이 권장되는 후속 작업 -->

# instructions/conventions.md

## 파일 점유 및 수정 규칙

1. IN_PROGRESS 파일은 assignee 에이전트만 수정할 수 있다.
2. TODO 파일을 IN_PROGRESS로 변경하기 전, 동일 ID의 IN_PROGRESS 파일이 없는지 반드시 확인한다.
3. 한 에이전트가 동시에 점유할 수 있는 작업은 최대 3개다.
4. DONE 파일은 어떤 에이전트도 수정할 수 없다. (append-only)

## 읽기 전용 파일

- `agents/*.md`: 에이전트 본인 파일만 수정 가능
- `instructions/*.md`: orchestrator 에이전트만 수정 가능
- `memories/decisions-log.md`: 결정 사항 추가만 허용, 기존 항목 수정 금지

## 충돌 발생 시 해결 절차

1. 충돌을 발견한 에이전트는 해당 task 파일의 `이슈` 섹션에 상황을 기록한다.
2. orchestrator 에이전트가 이를 감지하고 중재한다.
3. 중재 결과는 `memories/decisions-log.md`에 기록한다.

# 프로젝트명

## 프로젝트 개요
이 프로젝트는 [설명]을 목적으로 한다.

## 기술 스택
- Frontend: Next.js, TypeScript, Tailwind CSS
- Backend: Node.js, Prisma, PostgreSQL

## 에이전트 작업 시작 전 필수 확인 절차

이 프로젝트는 `.claude/` 디렉토리를 통해 에이전트 간 상태를 공유한다.
작업을 시작하기 전에 반드시 아래 순서로 파일을 읽어라.

1. `.claude/memories/project-context.md` — 프로젝트 목표와 배경
2. `.claude/instructions/conventions.md` — 협업 규칙 및 컨벤션
3. `.claude/tasks/` 전체 목록 스캔 — 현재 작업 현황
4. `.claude/agents/{자신의 역할}.md` — 자신의 역할과 원칙

## 핵심 협업 규칙 요약

- 작업 시작 시 task 파일명을 `IN_PROGRESS`로 변경하여 점유를 선언한다.
- 다른 에이전트의 `IN_PROGRESS` 파일은 수정하지 않는다.
- 완료 시 파일명을 `DONE`으로 변경하고 결과물 경로를 기록한다.
- `DONE` 파일은 append-only이며 내용을 수정할 수 없다.

## 협업 규칙
@.claude/instructions/conventions.md

## 도메인 용어
@.claude/instructions/domain-glossary.md