agent-workflow.md

Agent 개발 Workflow 가이드

Claude Code(Agent)와 함께 개발하는 나만의 흐름을 체계화한 문서. 3주차 이후에도 지속 가능하도록 작업 단위·프롬프트·검증 기준을 명문화한다. 큰 철학과 세션 패턴은 AI-WORKFLOW.md, 실행 도구는 .claude/ 참고.

---

1. 작업 단위 쪼개기 기준

1.1 기능 단위 (Feature) — "사용자가 인지하는 가치"

하나의 사용자 가치를 끝까지 동작시키는 수직 슬라이스. GitHub Issue 1개 = 기능 단위 1개가 기본.

• 예: "테마 입력 → 기업 후보 5~8개 반환"
• 포함 범위: 타입 → 데이터 어댑터 → AI 로직 → API route → 최소 UI
• 완료 정의(DoD): mock data로 end-to-end 동작 + 체크포인트 통과

1.2 컴포넌트 단위 (Component) — "독립적으로 테스트 가능한 조각"

기능 단위 안에서 다시 쪼개는 기준. 한 PR = 한 컴포넌트 단위가 기본.

• 예: ScoreCard UI / us-stock 어댑터 / theme-search 프롬프트
• 포함 범위: 단일 책임, 독립적으로 import·렌더·호출 가능

1.3 쪼개기 판단 플로우

이 작업이 사용자에게 보이는 가치 한 덩어리인가?
  ├─ 예 → 기능 단위 = Issue 로 등록
  └─ 너무 큼 → 컴포넌트 단위로 분해 = Issue 안의 체크박스 / 개별 PR

한 PR이 300줄을 넘거나 리뷰 관점이 2개 이상 섞이면 → 더 쪼갠다.
타입/계약은 항상 첫 번째 조각으로 분리한다 (다른 조각이 의존하므로).

1.4 Agent에게 맡기는 단위

• 한 세션 = 한 기능 단위 정도가 컨텍스트 관리에 적당
• 서로 의존 없는 컴포넌트(예: us-adapter / kr-adapter / 공통 타입)는 병렬(sub-agent) 요청
• 의존이 있으면 순차로, 앞 단계 산출물을 다음 프롬프트 맥락에 포함

---

2. AI 요청 프롬프트 패턴

2.1 기본 4요소

모든 요청은 [맥락] + [목표] + [제약] + [출력 형태] 를 채운다.

요소	무엇을	예시
맥락	관련 파일/현재 상태/Issue	"CLAUDE.md 읽고, lib/types/stock.ts 기준으로"
목표	이 세션의 결과물	"FMP 어댑터 + 캐싱까지"
제약	지켜야 할 규칙/비용	"mock 우선, 에러 graceful, 250req/day 고려"
출력 형태	코드/진단/제안 등	"타입부터 순서대로, 완료 시 리포트"

2.2 상황별 템플릿

기능 킥오프

CLAUDE.md 읽고 현재 상태 파악해줘.
오늘 목표: [기능]. 제약: mock 우선 / 에러 graceful.
타입 정의부터 순서대로 가자. 각 단계 끝나면 알려줘.

병렬 작업

서로 의존 없으니 병렬로 진행해줘:
1) [컴포넌트 A]  2) [컴포넌트 B]  3) [공통 타입]
각각 완료되면 리포트해줘.

프롬프트 개선 (/prompt-iteration)

[기능] 결과가 너무 generic해. 실제 출력 붙여줄게: [출력]
뭐가 문제인지 진단하고 v_next 만들어서 docs/prompts.md에 기록해줘.

리팩토링

[파일] 읽어봐. [증상]인 것 같아.
어떻게 분리하면 좋을지 먼저 제안만 해줘. 성능 영향 없어야 해.

세션 마무리

1) 변경분 Conventional Commits로 커밋  2) CLAUDE.md 진행 상황 업데이트
3) 다음 세션 이어서 할 것 기록

2.3 프롬프트 원칙

• "이 함수 만들어줘"(저맥락) 대신 판단을 요청한다 — Agent를 페어프로그래머로 쓴다
• 큰 결정(아키텍처/스키마)은 구현 전에 제안→검토→승인 단계를 둔다
• 결과가 애매하면 다시 시키기 전에 무엇이 왜 별로인지 구체적으로 피드백한다

---

3. 내가 직접 검증/판단해야 할 체크포인트

Agent가 "완료"라고 해도, 아래는 사람이 직접 확인한다. 통과 전엔 다음 단계로 안 넘어간다.

3.1 모든 작업 공통

• 변경 범위가 Issue/목표와 일치하는가 (scope creep 없는가)
• 타입/계약이 먼저 정의되고 나머지가 그걸 따르는가
• 커밋이 작업 단위로 쪼개졌고 메시지가 Conventional Commits인가
• mock으로 동작 확인했는가 (불필요한 실 API 호출 없는가)

3.2 외부 API (FMP)

• 응답 스키마가 실제와 일치하는가 (Agent 추정이 아니라 실데이터로 확인)
• 캐싱 TTL이 정책(docs/data-sources.md)과 맞는가
• 쿼터/비용 영향 (FMP 250 req/day) 고려됐는가
• 에러/빈응답이 graceful하게 처리되는가

3.3 AI 분석 로직 (Score / Bull-Bear)

• 점수 가중치가 PRD와 일치 (TAM 25 / 해자 20 / 경영진 15 / 재무 25 / 내러티브 15)
• 출력이 generic하지 않고 수치 근거가 있는가
• 프롬프트 변경이 docs/prompts.md에 버전 기록됐는가
• 동일 입력 재현성 / 비용(캐싱 6h) 확인

3.4 투자 도메인 리스크 (필수)

• 면책 조항이 노출되는가 ("참고용, 투자 권유 아님")
• 단정적 매수/매도 표현이 아니라 Risk/Reward 판단으로 제시되는가

3.5 머지 전

• feature/* → dev PR로 올렸는가 (직접 main push 아님)
• CLAUDE.md 진행 상황이 갱신됐는가
• 관련 Issue가 PR에 연결됐는가