Agent 개발 워크플로우

Claude Code(Agent)와 함께 개발하는 흐름을 체계화한 초안. 실행 도구는 레포의 .claude/ (슬래시 커맨드 + Skill), 단일 소스는 docs/agent-workflow.md.

1. 작업 단위 쪼개기 기준

기능 단위(Feature) = 사용자가 인지하는 가치 한 덩어리 → GitHub Issue 1개. (예: 테마 입력 → 후보 반환). 타입→어댑터→AI→API→최소 UI까지 수직 슬라이스.
컴포넌트 단위(Component) = 독립 테스트 가능한 조각 → PR 1개. (예: ScoreCard, us-stock 어댑터, theme-search 프롬프트).
판단 규칙: 사용자에게 보이는 가치면 기능 단위. 한 PR이 300줄↑이거나 리뷰 관점 2개↑면 더 쪼갠다. 타입/계약은 항상 첫 조각으로 분리.
Agent 배분: 한 세션 = 한 기능 단위. 의존 없는 조각은 병렬(sub-agent), 의존 있으면 순차로 산출물을 다음 맥락에 포함.

모든 요청 = [맥락] + [목표] + [제약] + [출력 형태].

요소	예시
맥락	"CLAUDE.md 읽고, lib/types/stock.ts 기준으로"
목표	"FMP 어댑터 + 캐싱까지"
제약	"mock 우선 / 에러 graceful / 250 req/day 고려"
출력	"타입부터 순서대로, 완료 시 리포트"

원칙: "이 함수 만들어줘"(저맥락) 대신 판단을 요청. 큰 결정은 구현 전에 제안→검토→승인. 결과가 별로면 무엇이 왜 별로인지 구체 피드백 후 재요청.

Agent가 "완료"라 해도 사람이 직접 확인:

공통: scope 일치 / 타입 우선 / 커밋 단위·컨벤션 / mock 동작 확인
외부 API: 응답 스키마 실데이터 확인 / 캐싱 TTL / 쿼터·비용 / graceful 에러
AI 로직: Score 가중치 PRD 일치(25/20/15/25/15) / generic 아님·수치 근거 / 프롬프트 버전 기록 / 재현성·비용
투자 도메인: 면책 노출 / 단정적 매수·매도 표현 금지(Risk·Reward로 제시)
머지 전: feature→dev PR / CLAUDE.md 갱신 / Issue 연결

주차가 지날수록 슬래시 커맨드·Skill·프롬프트 패턴을 누적·개선하고, docs/prompts.md(프롬프트 버전)와 docs/architecture.md(ADR)로 결정을 기록해 3주 이후에도 지속 가능하게 한다.