-
Notifications
You must be signed in to change notification settings - Fork 0
Agent 개발 workflow 흐름
조선하 edited this page May 28, 2026
·
1 revision
이 문서는 나만의 AI 요청 패턴을 정리한 것이다.
핵심은 내가 설계하고, AI는 실행한다. 맥락이 많을수록 결과가 좋다.
실제 워크플로우는 /workflow 명령으로 실행되며, Agent Skill이 단계를 순서대로 진행한다.
[design] checklist.md에서 feature 선택 → 구현 방법 합의 → 브랜치 생성
↓
[implement] 하위 항목 하나를 코드로 구현
↓
[review] 구현 코드 설명 + 피드백 수집
↓
├─ 피드백 있음 → [confirm] 수정 반영 → review 재진행
└─ 만족
↓
[commit] 변경사항 요약 + 커밋 안내
↓
├─ 미완료 하위 항목 있음 → implement로 돌아가 반복
└─ 모든 하위 항목 완료
↓
[push] push · PR 생성 · 브랜치 삭제 안내
각 단계는 사용자 확인 후 다음으로 넘어간다. AI가 단독으로 단계를 건너뛰지 않는다.
| 구분 | 기준 | 예시 |
|---|---|---|
| 기능 단위 | 독립적으로 동작 가능하고, 사용자가 "됐다"고 느낄 수 있는 크기 | 학생 등록 CRUD, 생기부 분석 API, 상담 기록 저장 |
| 컴포넌트 단위 | 화면 단위로 재사용 가능한 UI 조각 | StudentCard, AnalysisChart, ConsultationTimeline |
너무 크다 → AI가 한 번에 너무 많은 코드 생성, 검증 불가
딱 좋다 → 하나의 기능이 독립적으로 동작 가능한 단위, 브라우저에서 바로 확인 가능
너무 작다 → 컨텍스트 단절, 파편화된 구현
실무 체크: 내가 "이게 완성됐다"고 말할 수 있는 기준이 있는가?
없으면 더 쪼개거나, 완료 조건을 먼저 정의한다.
[1] 맥락 (Context) — 이 프로젝트가 뭔지, 지금 어느 단계인지
[2] 목표 (Goal) — 이번 요청에서 원하는 결과
[3] 제약 (Constraint) — 기술 스택, 파일 위치, 금지 패턴
[4] 완료 조건 (Done) — 내가 검증할 수 있는 기준
코드 바로 짜달라고 하지 말고 구조부터 제안받기.
이해 안 된 구조 위에 기능 얹으면 나중에 전부 무너진다.
[맥락]
이 프로젝트는 학생 입시 분석 서비스다.
기술 스택: React, Node.js + Express, MongoDB, Layered Architecture.
CLAUDE.md 원칙을 따른다. (checklist feature/1에서 작성 예정)
[목표]
생기부 분석 결과를 보여주는 화면의 컴포넌트 구조를 먼저 제안해줘.
코드는 아직 짜지 마.
[완료 조건]
- 어떤 컴포넌트가 필요한지
- 컴포넌트 간 props/데이터 흐름이 어떻게 되는지
- 파일 위치 제안
위 3가지가 포함된 구조 설계안을 만들어줘.
설계가 끝난 후 실제 코드를 요청할 때 쓴다.
구체적일수록 AI가 틀릴 확률이 줄어든다.
[맥락]
프로젝트: studentanalysis (입시 분석 서비스)
기술 스택: React, CSS Modules, Vite
현재 상태: StudentDetail 페이지가 있고, 탭 구조로 구성됨
[목표]
AnalysisResultCard 컴포넌트를 만들어줘.
[제약]
- 파일 위치: client/src/components/AnalysisResultCard/AnalysisResultCard.jsx
- props: analysisResult, isLoading
- CSS Modules 사용, 외부 UI 라이브러리 없음
[완료 조건]
- isLoading이 true면 스켈레톤 UI 노출
- analysisResult의 5단계 결과를 각각 섹션으로 렌더링
- 브라우저에서 레이아웃 깨짐 없이 확인 가능
내 스펙에 뭔가 빠진 것 같을 때.
AI가 임의로 채우기 전에, 내가 먼저 빈칸을 찾는다.
[맥락]
아래 스펙을 구현하려고 한다:
- 생기부 분석 버튼 클릭 → OpenAI API 호출 → 5단계 분석 결과 저장
[목표]
이 스펙에서 구현하려면 더 결정해야 할 것들이 뭐가 있는지 물어봐줘.
코드는 짜지 말고, 빠진 결정사항 목록만 뽑아줘.
[완료 조건]
각 항목마다 "왜 이게 필요한지"도 한 줄씩 설명
AI가 만든 코드를 이해 없이 붙여넣으면 안 된다.
작동하는 코드와 이해한 코드는 다르다.
방금 만들어준 코드에서 [useCallback / useEffect의 의존성 배열 / Promise.all] 을 쓴 이유가 뭐야?
없어도 되는 경우는 언제고, 꼭 필요한 경우는 언제야?
내 코드에서는 어느 쪽에 해당해?
"이상해요 고쳐줘"는 금지.
뭐가 왜 다른지 말해야 AI가 맞게 고친다.
[현재 동작]
분석 결과 카드들이 세로로 쌓이고 있다.
[의도한 동작]
데스크탑에서는 2열 그리드로 나열돼야 한다.
[의심되는 원인]
flex-direction이 column으로 설정된 것 같다.
다음 기능 얹기 전에 구조 정리.
기준을 명확히 줘야 AI가 과도하게 바꾸지 않는다.
[맥락]
StudentDetail.jsx가 너무 길어졌다 (300줄 이상).
[목표]
아래 기준으로만 리팩토링해줘. 기능 변경 없이.
[리팩토링 기준]
1. 중복 로직 제거
2. 하드코딩된 상수 분리 (constants.js)
3. 컴포넌트 단일 책임 — 데이터 fetch와 UI 렌더링 분리
4. 그 외는 건드리지 마
[완료 조건]
리팩토링 후에도 기존 동작이 동일해야 함
변경된 파일 목록과 이유 한 줄씩 설명
완성됐다고 생각할 때 마지막으로 구멍을 찾는다.
[맥락]
학생 상담 기록 저장 기능을 방금 완성했다.
[목표]
이 기능에서 내가 놓쳤을 수 있는 엣지케이스를 뽑아줘.
[범위]
- 프론트엔드 입력 검증
- API 에러 케이스 (네트워크 오류, 400/500 응답)
- 빈 값, 특수문자, 매우 긴 입력
- 사용자 입장에서 헷갈릴 수 있는 UX
[완료 조건]
각 케이스마다 "현재 처리되고 있는가 / 처리 안 되고 있는가" 표시
- 내가 설계한 대로 만들었는가?
- 이해 안 되는 코드가 있는가? (있으면 그 자리에서 물어본다)
- 내가 요청하지 않은 것이 들어왔는가?
- CLAUDE.md 금지 패턴이 포함됐는가? (any 타입, 외부 라이브러리 등)
- 의도한 레이아웃으로 보이는가?
- 로딩 상태가 노출되는가?
- 에러 상태가 처리됐는가?
- 개발 환경에서만 동작하는 코드가 없는가? (fetch('/src/data/...') 같은 패턴)
- 컨벤션 준수 (커밋 메시지 형식, 파일명 규칙)
- 콘솔 에러 없음
- 환경변수 노출 없음
- 하드코딩된 매직 넘버 없음
- feature 브랜치에서 작업했는가?
- 기능 하나 = 커밋 하나 원칙 지켰는가?
- 리팩토링을 다음 기능 전에 했는가?
CLAUDE.md는 checklist feature/1에서 작성 예정. 현재는 아래 내용이 기준.
작성 완료 후 실제 파일 기준으로 업데이트한다.
# 이 프로젝트
studentanalysis-jsh — 학생 입시 분석 서비스
# 기술 스택
React / Node.js + Express / MongoDB / Vite
# 아키텍처
- 레이어드: routes → services → repositories → models
- 상태는 커스텀 훅으로 분리, App.jsx에 직접 두지 않음
- 컴포넌트: PascalCase, 파일명 = 컴포넌트명
# 하지 말 것
- any 타입 금지
- 외부 UI 라이브러리 금지
- Controller에 비즈니스 로직 금지
- 500 에러 내부 메시지 노출 금지
# 커밋 형식
feat / fix / refactor / docs / chore
| 실수 | 대응 |
|---|---|
| 설계 없이 AI에게 바로 요청 | 패턴 A로 구조 먼저 물어보기 |
| "이상해요 고쳐줘" | 패턴 E로 현재/의도한 동작 명확히 설명 |
| AI 코드 이해 없이 붙여넣기 | 패턴 D로 이해 안 되는 부분 물어보기 |
| 한 번에 여러 기능 요청 | 기능 하나씩, 완료 후 커밋 후 다음 기능 |
| 확인 안 하고 다음 기능으로 | 브라우저 체크포인트 목록 필수 |
| 리팩토링 미루기 | 다음 기능 얹기 전 패턴 F 적용 |
이 문서는 개발하면서 계속 업데이트한다.
처음 정한 패턴이 맞지 않으면 바꾼다. 패턴도 내 것이어야 한다.