🤖가이드

Claude 코드 에이전트 워크플로우 원칙

AI 에이전트가 코드 작업을 효율적으로 수행하기 위한 6가지 핵심 워크플로우 원칙과 실천 방법

↗ 원본 링크

#Claude#에이전트#워크플로우#코드리뷰#자동화

Claude 코드 에이전트 워크플로우 원칙

AI 에이전트가 코드 작업을 수행할 때 따라야 할 체계적인 워크플로우 원칙을 소개합니다.

6가지 핵심 워크플로우

1. 기본 계획 모드

복잡한 작업은 반드시 계획부터 세우세요.

▸3단계 이상의 작업은 계획 모드로 진입

▸문제 발생 시 즉시 멈추고 재계획

▸빌드뿐 아니라 검증 단계에서도 계획 사용

▸모호함을 줄이기 위한 상세 사양 작성

2. 서브 에이전트 전략

메인 작업의 컨텍스트를 깨끗하게 유지하세요.

▸조사 및 탐색 작업은 서브 에이전트에 위임

▸복잡한 문제는 서브 에이전트로 병렬 처리

▸서브 에이전트당 하나의 집중 작업 할당

3. 자기 개선 루프

같은 실수를 반복하지 마세요.

markdown

# tasks/lessons.md 예시
- [2024-01-15] API 호출 전 항상 에러 핸들링 추가
- [2024-01-16] 타입 변경 시 관련 테스트 코드도 함께 수정

▸수정 사항을 `tasks/lessons.md`에 기록

▸세션 시작 시 교훈 검토

▸실수율이 떨어질 때까지 반복 개선

4. 완료 전 검증

작동을 증명하지 않으면 완료가 아닙니다.

체크리스트:

▸✅ 테스트 실행 완료

▸✅ 로그 확인 완료

▸✅ 메인 브랜치와 동작 비교

▸✅ 스태프 엔지니어 수준의 품질

5. 우아함 추구

임시방편이 아닌 근본적인 해결책을 찾으세요.

판단 기준:

▸사소한 변경 → 빠르게 처리

▸복잡한 변경 → "더 우아한 방법은?"

▸미봉책처럼 느껴짐 → 재설계 고려

6. 자율적 버그 수정

버그를 발견하면 바로 수정하세요.

▸사용자에게 일일이 물어보지 않기

▸실패한 CI 테스트 자동 수정

▸로그와 오류를 분석하고 즉시 해결

작업 관리 프로세스

작업 흐름

markdown

1. tasks/todo.md에 계획 작성
2. 사용자에게 계획 검증 요청
3. 진행하며 완료 항목 체크
4. 각 단계별 요약 제공
5. tasks/todo.md에 결과 문서화
6. tasks/lessons.md에 교훈 기록

todo.md 예시

markdown

# TODO

## 계획
- [ ] API 엔드포인트 설계
- [ ] 데이터베이스 스키마 업데이트
- [ ] 테스트 코드 작성

## 완료
- [x] 요구사항 분석

## 검토
- 변경 사항: 새로운 사용자 인증 API 추가
- 영향 범위: auth 모듈만 수정

3가지 핵심 원칙

1. 단순함 우선

▸가능한 한 단순하게

▸코드 영향 최소화

▸이해하기 쉬운 구조

2. 나태함 금지

▸근본 원인 해결

▸임시방편 거부

▸시니어 개발자 수준 유지

3. 최소한의 영향

▸필요한 부분만 수정

▸버그 유입 방지

▸사이드 이펙트 최소화

실전 적용 팁

작업 시작 전

1.tasks/lessons.md 검토

2.복잡도 평가 (3단계 이상?)

3.계획 모드 필요 여부 판단

작업 중

1.문제 발생 시 즉시 재계획

2.서브 에이전트 활용 고려

3.진행 상황 지속 기록

작업 완료 전

1.테스트 실행 및 검증

2.코드 리뷰 (자기 검토)

3.교훈 문서화

마치며

이 워크플로우는 AI 에이전트가 체계적이고 효율적으로 코드 작업을 수행하도록 돕습니다. 핵심은 계획 → 실행 → 검증 → 학습의 순환 구조입니다.

사람이 작업할 때도 동일하게 적용할 수 있는 좋은 실천 방법들이니, 개발 워크플로우 개선에 참고해보세요!