에이전트 설계서 작성 프롬프트

나는 [작업명]을 자동화하는 에이전트 시스템을 설계하려고 한다. ## 작업 개요 - **목적**: - **입력**: - **출력**: - **주요 제약조건**: --- ## 내가 원하는 산출물 최종적으로 **하나의 통합 설계서 문서(md 파일)**를 만들고 싶다. 이 문서는 Claude Code에서 구체적인 구현을 할 때 참조할 **계획서** 역할을 한다. ### 설계서에 포함될 내용 1. **작업 컨텍스트 문서** - 배경, 목적, 범위, 입출력 정의, 제약조건, 용어 정의 2. **워크플로우 정의** - 단계별 흐름도, 분기조건, 상태 전이 - LLM 판단 영역과 코드 처리 영역 구분 - LLM이 직접 수행할 판단/의사결정 단계 명시 - 각 단계의 성공 기준 및 검증 방법 - 실패 시 처리 방식 (재시도 / 에스컬레이션 / 스킵) 3. **구현 스펙** (구조 개요만, 상세 내용 X) - 폴더 구조 - CLAUDE.md 핵심 섹션 목록 - 에이전트 구조 (단일 또는 서브에이전트) - 작업 단계별 처리 방식 (에이전트 판단 vs 스크립트) - 스킬/스크립트 파일 목록, 역할, 트리거 조건(언제 이 스킬이 호출되는가) - 서브에이전트 사용 시: 이름, 역할, 입출력, 데이터 전달 방식 - 주요 산출물 파일 형식 --- ## 설계 원칙 ### [폴더 구조] 에이전트 설정은 `/.claude` 하위에 배치한다. ``` /project-root ├── CLAUDE.md # 메인 에이전트 지침 ├── /.claude │ ├── /skills/<skill-name> │ │ ├── SKILL.md │ │ ├── /scripts # 결정론적 도구 │ │ └── /references # (선택) 도메인 지식, API 가이드 등 │ └── /agents/<subagent-name> │ └── AGENT.md ├── /output # 산출물 └── /docs # (선택) 참고 문서 ``` ### [판단과 코드의 역할 분리] | 에이전트가 직접 수행 | 스크립트로 처리 | |---------------------|----------------| | 분류, 의사결정, 우선순위 판단 | 파일 I/O, 데이터 파싱 | | 품질 평가, 정성적 분석 | 외부 API 호출 | | 컨텍스트 기반 추론 | 반복 처리, 집계 | | 자연어 생성/요약 | 정적 분석, 테스트 실행 | ### [검증 패턴] 각 워크플로우 단계에는 반드시 성공 기준을 정의한다. 검증 유형은 산출물 성격에 따라 선택한다. | 검증 유형 | 적용 대상 | 예시 | |-----------|----------|------| | **스키마 검증** | 구조화된 산출물 | 필수 필드 존재, 타입 체크 | | **규칙 기반** | 정량 기준이 있는 작업 | 항목 수, 글자 수, 필수 섹션 포함 | | **LLM 자기 검증** | 정성적 판단 작업 | 요약 품질, 톤 적합성, 누락 여부 | | **사람 검토** | 고위험 최종 산출물 | 외부 발송 문서, 의사결정 | 설계서 작성 시 각 단계마다 다음을 명시한다: - **성공 기준**: 이 단계의 산출물이 충족해야 할 조건 - **검증 방법**: 위 유형 중 어떤 방식으로 확인하는가 - **실패 시 처리**: 아래 패턴 중 선택 ### [실패 처리] | 방식 | 사용 시점 | |------|----------| | **자동 재시도** | 검증 실패가 단순 누락/형식 오류인 경우 (최대 재시도 횟수 명시) | | **에스컬레이션** | 판단 불확실성이 높거나 기준 자체가 모호한 경우 → 사람에게 확인 요청 | | **스킵 + 로그** | 선택적 단계이며 전체 흐름에 영향 없는 경우 → 사유를 로그에 기록 | ### [에이전트 구조 선택] **단일 에이전트** (기본): - 워크플로우가 단순하고 지침이 짧을 때 **서브에이전트 분리** (필요 시): - **컨텍스트 윈도우 최적화가 필요할 때** -- 지침이 길어서 항상 로드하면 비효율적인 경우, 서브에이전트로 분리하여 필요한 시점에만 해당 지침 로드 - 독립적인 작업 블록이 명확히 구분되고, 각각 다른 도메인 지식이 필요할 때 ### [서브에이전트 설계] - 메인 에이전트(CLAUDE.md)가 오케스트레이터 역할 - 서브에이전트 간 직접 호출 금지 → 메인을 통해 조율 - AGENT.md에 역할, 트리거 조건, 입출력, 참조 스킬 명시 ### [데이터 전달 패턴] | 방식 | 사용 시점 | |------|----------| | **파일 기반** | 데이터가 크거나 구조화된 경우 → `/output/step1_result.json` | | **프롬프트 인라인** | 데이터가 작고 단순한 경우 | 권장: 중간 산출물은 `/output/`에 저장하고 파일 경로만 전달 ### [스킬 vs 서브에이전트] | 스킬 | 서브에이전트 | |------|-------------| | 도구/기능 단위 (작음) | 역할/책임 단위 (큼) | | 여러 에이전트가 공유 가능 | 특정 워크플로우 전용 | | 예: `file-parser`, `api-caller` | 예: `code-reviewer`, `report-generator` | --- ## 주의사항 - CLAUDE.md, AGENT.md, 스킬 파일의 **상세 내용은 작성하지 않는다** (구현 시 작성) - 구현 스펙은 **구조와 역할 정의 수준**까지만 --- ## 진행 방식 ### 1단계: 작업 파악 (필수 확인 항목) 사용자 입력을 받으면 아래 세 영역의 정보가 충분한지 판단한다. **부족한 영역이 있으면 해당 영역의 질문만 한다. 모두 충분하면 바로 설계에 착수한다.** | 영역 | 확인할 것 | 부족할 때 질문 예시 | |------|----------|-------------------| | **목표와 성공 기준** | 이 에이전트가 궁극적으로 달성해야 할 목표가 명확한가? 성공/실패를 판단할 수 있는 기준이 있는가? | "이 에이전트가 잘 작동했다는 걸 어떻게 알 수 있나요? 어떤 결과가 나와야 성공인가요?" | | **작업 절차** | 입력→출력까지의 구체적 단계가 있는가? 분기 조건이 명확한가? | "A 이후에 B로 갈지 C로 갈지는 어떤 기준으로 판단하나요?" | | **에이전트 조직** | 단일/멀티 에이전트 선호가 있는가? 역할 분리 기준이 있는가? | "이 작업을 하나의 에이전트가 순차 처리하면 되나요, 아니면 분리하고 싶은 역할이 있나요?" | | **기술/도구 대안** | 현재 쓰는 도구가 있는가? 없다면 목적에 맞는 도구·API·라이브러리를 역제시하여 선택을 도울 수 있는가? | "지금 쓰고 있는 도구가 있나요? 없다면 이런 방식들이 가능한데, 어떤 게 상황에 맞을 것 같나요?" | ### 질문 원칙 - 질문은 뻔하거나 상투적이지 않아야 하며, 매우 심층적으로 접근하여 내용이 완성될 때까지 인터뷰를 계속 이어가야 합니다 (최대 3턴) - 사용자가 모르겠다고 하면 설계 원칙에 따라 LLM이 판단하고 그 근거를 명시한다 - 사용자가 "알아서 해줘"라고 하면, 합리적 기본값을 적용하되 핵심 선택지만 확인한다 ### 2단계: 설계서 작성 확인이 끝나면 "설계서에 포함될 내용"에 따라 통합 설계서(md 파일)를 작성한다. ### 3단계: 리뷰 설계서 초안을 제시하고, 수정할 부분이 있는지 확인한다.