Agent Setup

Core Goal

두 영역을 단일 인터페이스로 통합한다:

기본값: --focus both — 새 에이전트 세팅에는 둘 다 필요하다.

Trigger Gate

Use This Skill When

• 새 에이전트 환경 전체 세팅 → --focus both
• 에이전트 System Prompt + 7요소만 설계 → --focus instructions
• 프로젝트 CLAUDE.md / AGENTS.md 생성·개선만 → --focus claude-md
• 기존 인스트럭션 최적화·디버깅 → --focus instructions --level draft
• 팀원 온보딩을 위한 프로젝트 컨텍스트 공유 → --focus claude-md

Route to Other Skills When

• 컨텍스트 윈도우 예산 계획 → deliver/prd Section 9 (메모리 설계)
• PRD 공식 문서화 → deliver/prd
• 에이전트 설계 구현 전 4축 검증 → deliver/conductor (Spec Compliance 게이트)

Boundary Checks

• --focus 미명시 → both 기본값 진입 + 사용자 안내
• Anti-Goals 없으면 instructions/both 모두 경고 (Anti-Goals는 에이전트 설계 필수)
• Tool 목록에 사용 조건 없으면 경고 (도구 남용 방지)
• CLAUDE.md는 프로젝트 레벨 컨텍스트 문서이지 에이전트 Instruction이 아님

Inputs

Instructions

You are setting up the agent environment with arguments: $ARGUMENTS

공통 Step 0 — focus 파싱

args = parse("$ARGUMENTS")
focus = args.get("--focus", "both")   # 기본값: both
level = args.get("--level", "full")   # instructions focus 시 기본값: full
target = args remainder after options

focus 미명시 시:

"--focus 미명시 — --focus both 기본값으로 진입합니다. 사용 가능: --focus instructions|claude-md|both"

focus: instructions

instructions의 역할: System Prompt + 7요소 + tool list + memory_config 완전 명세. "신입 직원 온보딩 문서" 수준.

--level draft (PM 관점 프롬프트 설계)

Step 1 — CRISP 5요소 채우기

• 최소 4요소 명시 (Scope·Parameters는 선택 아님)
• 각 지시마다 "왜(Why)" 1줄 추가 (Why-First 원칙)

Step 2 — 판단 기준 명시화

[상황 A]이면 → [행동 X]  이유: ...
[상황 B]이면 → [행동 Y]  이유: ...
판단 어려우면 → [에스컬레이션]

Step 3 — Anti-Goals 추가 (최소 3개)

• 절대 하지 말아야 할 것, 구체적 시나리오로

Step 4 — 실패 처리 추가

• 데이터 없음 / API 실패 / 판단 불확실 케이스

Step 5 — 7가지 실패 패턴 체크

Step 6 — Why-First 검토

• 에이전트가 "왜 이 작업을 하는지"가 주요 지시마다 녹아 있는가

--level full (완전 명세, 기본값)

Step 1 — Role 작성 (요소 1)

• 에이전트 역할, 대상 사용자, 전문성 범위 1~3문장
• 구체적 도메인 명시 (일반 어시스턴트 X)

Step 2 — Context 정리 (요소 2)

• 사용자 프로필 (역할, 언어, 기술 수준)
• 실행 환경 (cron / 대화형 / 이벤트 트리거)
• 접근 가능한 데이터 소스 목록

Step 3 — Objective 계층 설계 (요소 3)

• Primary Goal 1개 (측정 가능)
• Secondary Goals 우선순위 순 나열
• Anti-Goals 최소 3개 (구체적 시나리오)

Step 4 — Tools 목록 작성 (요소 4)

| 도구 | 용도 | 사용 조건 | 제한 |

• 최소 권한 원칙: 필요한 도구만
• 비용이 큰 도구 호출 횟수 명시
• 도구별 "사용하면 안 되는 경우" 명시

Step 5 — Memory Strategy 설계 (요소 5)

단기 (컨텍스트 윈도우): 현재 세션에서만 필요한 정보
장기 (파일):            세션 간 유지해야 할 정보 + 파일 경로
절차적 (SKILL.md):      반복 판단 패턴 외부화

Step 6 — Output Format 정의 (요소 6)

채널:   [Telegram / 파일 / stdout / Notion]
형식:   [Markdown / Plain / JSON]
길이:   [최대 N줄]
언어:   [한국어 / 영어]
톤:     [간결 / 상세]

Step 7 — Failure Handling 작성 (요소 7)

| 실패 시나리오 | 감지 방법 | 행동 |

• 4가지 이상 실패 시나리오별 행동 정의
• Human-in-the-loop 개입 조건 명시

focus: claude-md

claude-md의 역할: 프로젝트 디렉토리를 스캔하여 CLAUDE.md 및 AGENTS.md를 생성·개선한다.

Phase 1 — 프로젝트 스캔 (Scan)

1. 기술 스택 감지: 설정 파일 읽어 프레임워크, 언어, 의존성 파악
   • package.json → dependencies, devDependencies, scripts
   • pyproject.toml / requirements.txt → Python 패키지
   • tsconfig.json → TypeScript 설정
2. 아키텍처 분석: 디렉토리 구조 탐색
3. 컨벤션 추론: 실제 코드에서 패턴 추출
4. 기존 CLAUDE.md 확인: 있으면 "개선 모드"로 전환

Phase 2 — CLAUDE.md 생성 (Build)

9룰 구조 적용:

# CLAUDE.md

## 프로젝트 개요
[1~2문장]

## 기술 스택
[프레임워크, 언어, 주요 라이브러리 — 버전 포함]

## 빌드 & 실행
[실제 동작하는 명령어만]

## 코드 컨벤션
[네이밍, 디렉토리, 스타일]

## 아키텍처
[디렉토리 구조 + 데이터 흐름]

## 주의사항 (Anti-Goals)
[Claude Code가 하면 안 되는 것]

설계 원칙:

• 온보딩 문서 수준의 완성도 (새 팀원이 첫날 읽는 문서)
• 구체적 > 일반적 (Next.js 14 App Router vs "React 사용")
• 실행 가능한 명령어만 기록
• Anti-Goals 포함 필수
• 목표: 1,500~3,000 tokens

Phase 3 — AGENTS.md 생성 (에이전트 프로젝트일 때)

agents/ 디렉토리 또는 instructions/ 디렉토리가 있을 때:

# AGENTS.md

## 에이전트 구조
[에이전트 목록 + 각 역할]

## 인스트럭션 7요소 표준
[프로젝트 표준 인스트럭션 패턴]

## 에이전트 간 의존성
[오케스트레이션 흐름]

## 주의사항
[에이전트 수정 시 지켜야 할 규칙]

focus: both (기본값)

Step 1 → --focus instructions --level full 실행하여 7요소 완전 명세 생성

Step 2 → 생성된 인스트럭션 결과를 컨텍스트로 받아 --focus claude-md 실행

두 단계 순서 고정: instructions 먼저, claude-md 나중 (에이전트 정체성이 확정된 후 메모리 파일 작성).

Failure Handling

Quality Gate

instructions (draft)

• CRISP 5요소 중 최소 4개 명시
• Anti-Goals 최소 3개 (구체적 시나리오)
• 판단 기준 정량적 또는 구체적 예시
• 7가지 실패 패턴 모두 체크
• Why-First 원칙 적용 (주요 지시마다 "왜")

instructions (full)

• 7요소 모두 포함 (Role/Context/Objective/Tools/Memory/Output/Failure)
• Anti-Goals 최소 3개 (구체적 시나리오)
• 각 Tool 사용 조건 + 제한 명시
• Memory 3계층 (단기/장기/절차적) 정의
• Failure Handling 4가지 이상

claude-md

• 프로젝트 기술 스택 정확히 식별됨
• 빌드/테스트/린트 명령어가 실제 동작하는 명령어임
• Anti-Goals(주의사항) 포함
• 1,500~3,000 tokens 범위
• 에이전트 프로젝트이면 AGENTS.md도 생성됨

Examples

Good Example

입력: --focus both "news-summarizer 에이전트"

기대 동작:

1. instructions/full: Role(PM 정보 수집 파트너) → 7요소 완전 명세
2. claude-md: 프로젝트 스캔 → CLAUDE.md + AGENTS.md 생성

Good Example

입력: --focus instructions --level draft "아침 뉴스 요약 프롬프트 최적화"

기대 동작:

1. CRISP 5요소 채우기
2. 판단 기준 테이블 (상황 → 행동)
3. Anti-Goals 3개 이상 (구체적)
4. 7가지 패턴 체크 → 최종 프롬프트

Bad Example

입력: --focus instructions "뭔가 에이전트"

기대 동작: "에이전트 목적이 불명확합니다. 구체적인 에이전트명 또는 목적을 입력해주세요." fail loud

Project Context (auto-loaded)

프로젝트 메모리: !cat .claude/MEMORY.md 2>/dev/null || echo "프로젝트 메모리 없음"

기존 에이전트 인스트럭션: !ls -1 agents/*/INSTRUCTION.md 2>/dev/null || ls -1 instructions/*.md 2>/dev/null || echo "기존 인스트럭션 파일 없음"

기존 CLAUDE.md (개선 모드 감지용): !cat CLAUDE.md 2>/dev/null || echo "CLAUDE.md 없음 — 새로 생성 모드"

프로젝트 구조 스냅샷: !find . -maxdepth 2 -type f \( -name "package.json" -o -name "pyproject.toml" -o -name "tsconfig.json" -o -name "Dockerfile" \) 2>/dev/null | head -10 || echo "설정 파일 없음"