문제: 아무도 이야기하지 않는 문제
생산적인 척하는 루프:
→ Claude에게 기능을 만들어 달라고 요청 → 코드를 생성함 → 뭔가가 깨짐 → 에러를 다시 붙여넣기 → 패치함 → 또 다른 문제가 발생함 → 다시 요청
첫째 날: 마법처럼 느껴짐.
30일째: 예전에 코드를 작성하던 시간보다 AI를 감독하는 데 더 많은 시간을 쓰고 있음.
같은 로직이 3군데에서 나타남.
Claude가 2주 전에 설정한 규칙을 잊어버림.
새로운 기능이 기존 기능을 망가뜨림.
테스트가 누락되었거나 얕음.
깨어나서 깨닫게 됨: AI가 실패한 게 아님.
당신의 워크플로우가 실패한 것임.
진짜 문제는 구조적입니다.
Claude Code에 "이 기능을 만들어 줘"라고 입력할 때, 하나의 AI 세션에게 다음과 같은 역할을 동시에 요구하는 것입니다:
→ 제품 분석가 → 아키텍트 → 백엔드 엔지니어 → 프론트엔드 엔지니어 → 테스트 엔지니어 → 코드 리뷰어
동시에요.
같은 복잡한 대화 속에서요.
계획의 잘못된 가정이 잘못된 데이터베이스 모델이 됩니다.
잘못된 데이터베이스 모델이 잘못된 API가 됩니다.
잘못된 API가 잘못된 UI가 됩니다.
당신이 알아차릴 때쯤이면, 실수는 이미 모든 곳에 퍼져 있습니다.
이것을 '바이브 코딩'이라고 합니다.
그리고 여기에는 명확한 한계가 있습니다.
전환: 바이브 코딩에서 소프트웨어 팩토리로
실제로 모든 것을 바꾸는 것:
진짜 엔지니어링 팀은 하나의 큰 대화로 일하지 않습니다.
서로 다른 사람이 서로 다른 작업을 담당합니다:
→ 누군가는 사용자 문제를 명확히 합니다 → 누군가는 아키텍처를 고민합니다 → 누군가는 API를 구축합니다 → 누군가는 UI를 구축합니다 → 누군가는 예외 케이스를 고민합니다 → 누군가는 리뷰합니다
이 모든 것을 하나의 AI 세션에 집어넣으면, 실수가 조용히 누적됩니다.
해결책은 작업을 전문 에이전트들에게 분할하는 것입니다.
각 에이전트는 다음을 받습니다: → 하나의 집중된 작업 → 자신만의 깨끗한 컨텍스트 윈도우 → 실제로 필요한 도구만 → 건드릴 수 없는 것에 대한 엄격한 규칙
결과: 소프트웨어 팩토리.
개발자 1명 + 집중된 에이전트 7명 = 조정된 팀.
다음은 이를 가능하게 하는 7가지 에이전트입니다.
7가지 에이전트
에이전트 1: 코드베이스 리서처
개발자들이 AI로 가장 많이 저지르는 실수는?
첫 번째 움직임으로 코드를 요청하는 것입니다.
AI는 프롬프트를 받아들이고, 빈틈을 메우기 위해 추측을 하고, 생성을 시작합니다.
그때 나쁜 설계가 스며듭니다.
코드베이스 리서처가 이를 해결합니다.
유일한 임무: 한 줄의 코드도 작성되기 전에 코드베이스를 조사하고 어떻게 작동하는지 설명하는 것.
하는 일: → 관련 파일과 그 역할을 매핑 → 따라야 할 기존 패턴 문서화 → 이미 구축된 유사 기능 찾기 → 위험 요소 플래그 지정 (시간대, 멀티 테넌트, 재시도 로직) → 업데이트가 필요한 테스트 목록 작성
할 수 없는 일: → 파일 편집 (읽기 전용 액세스만) → 상태를 수정하는 명령 실행 → 가정하지 않음 — 대신 질문함
도구: 읽기, Grep, Glob만.
규칙: 탐색 후 구축, 매번.
리서처가 먼저 실행됩니다. 항상.
에이전트 2: 스토리 라이터
대부분의 기능은 코드가 잘못되어서 실패하는 것이 아닙니다.
문제가 명확하게 정의되지 않았기 때문입니다.
스토리 라이터는 기술적 결정이 내려지기 전에 대략적인 기능 아이디어를 실제 사용자 스토리로 바꿉니다.
입력으로 받는 것: → 대략적인 기능 설명 → 리서처의 결과물
생성하는 것:
하나의 사용자 스토리: "[역할]로서 [행동]을 원합니다. 그래서 [결과]를 얻습니다."
승인 기준:테스트가 직접 검증할 수 있는 문장. 정상 경로. 실패 경로. 비즈니스 규칙.
예외 케이스:경계값, 재시도, 멀티 테넌트 관련 사항.
범위 외:명시적으로 구축하지 않는 것.
미해결 질문:진정으로 알지 못하는 것 — 절대 추측하지 않음.
할 수 없는 일: → 비즈니스 규칙을 발명 → 코드나 기술 설계 작성 → 명확하지 않은 부분이 있으면 진행
도구: 읽기만.
규칙: 다른 모든 작업 전에 이 스토리를 읽고 승인합니다.
이것이 다운스트림의 모든 것을 구하는 인간 체크포인트입니다.
에이전트 3: 스펙 라이터
스토리가 승인되면, 스펙 라이터는 이를 기술 브리프로 전환합니다.
이것은 모든 빌드 에이전트가 따르는 청사진입니다.
입력으로 받는 것: → 승인된 사용자 스토리 → 리서처의 결과물 → 프로젝트의 CLAUDE.md 규칙
생성하는 것:
→ 데이터 모델 변경 사항 (필드, 유형, 마이그레이션) → 백그라운드 흐름 / 프로세스 흐름 → API 변경 사항 (엔드포인트, 요청/응답 형태) → 프론트엔드 변경 사항 (컴포넌트, 페이지, 훅) → 필요한 테스트 (성공, 실패, 예외 케이스) → 위험 요소 및 미해결 질문 → 변경될 모든 파일
할 수 없는 일: → 파일 편집 → 새로운 인프라를 발명 — 대신 명시적으로 언급 → 테넌트 격리 또는 시간대 문제를 건너뛰기 → 질문에 답하지 않은 채로 두기
도구: 읽기, Grep, Glob만.
규칙: 이 브리프는 두 번째 인간 체크포인트입니다.
단 하나의 파일도 건드리기 전에 읽고 승인합니다.
"메모리에 ID 저장"을 보게 된다면 — 그게 당신의 위험 신호입니다.
지금 잡으세요. 10개의 파일이 변경된 후가 아닙니다.
에이전트 4: 백엔드 빌더
이제 구축이 시작됩니다.
백엔드 빌더는 기능의 백엔드 부분만 구현합니다 — 정확히 백엔드만.
입력으로 받는 것: → 승인된 기술 브리프 → 리서처의 결과물 → 프로젝트의 CLAUDE.md
구축하는 것: → API 라우트 → 서비스 및 비즈니스 로직 → 데이터베이스 액세스 및 마이그레이션 → 백그라운드 작업 → 작성하는 모든 것에 대한 단위 테스트
할 수 없는 일: → React 컴포넌트, 페이지 또는 클라이언트 측 훅 건드리기 (에이전트 5의 역할) → 지시 없이 새 종속성 발명 → 합의된 범위를 벗어난 파일 수정 → 타입체크, 린트, 테스트 스위트를 실행하지 않고 중단
완료 후 요약 반환: → 추가되거나 편집된 모든 파일 → 재사용된 기존 헬퍼 또는 패턴 → 도움이 되었을 CLAUDE.md 규칙
도구: 읽기, 편집, 쓰기, Bash — 백엔드 폴더로만 범위 제한.
분리가 핵심입니다.
백엔드 빌더는 프론트엔드를 절대 실수로 망가뜨리지 않습니다.
에이전트 5: 프론트엔드 빌더
프론트엔드 빌더는 UI 부분만 구현합니다 — 정확히 UI만.
먼저 백엔드 빌더의 요약을 읽습니다.
이것이 중요합니다.
백엔드가 생성한 그대로의 API를 사용합니다.
새로운 엔드포인트를 발명하지 않습니다.
UI에 API 형태가 맞지 않으면, 패치가 아닌 피드백으로 불일치를 표면화합니다.
입력으로 받는 것: → 승인된 기술 브리프 → 리서처의 결과물 → 백엔드 빌더의 요약 (API 계약)
구축하는 것: → React 컴포넌트 및 페이지 → 클라이언트 측 훅 및 상태 → 로딩 및 오류 상태 → 작성하는 모든 것에 대한 컴포넌트 및 단위 테스트
할 수 없는 일: → 서비스, API 라우트, 워커 또는 마이그레이션 건드리기 (에이전트 4의 역할) → 엔드포인트 또는 응답 형태 발명 → 지시 없이 종속성 추가 → 타입체크, 린트, 테스트 스위트를 실행하지 않고 중단
도구: 읽기, 편집, 쓰기, Bash — 프론트엔드 폴더로만 범위 제한.
두 명의 빌더.
두 개의 깨끗한 컨텍스트 윈도우.
한쪽이 다른 쪽의 작업을 망가뜨릴 확률 제로.
에이전트 6: 테스트 검증기
두 빌더 모두 자신의 코드에 대한 단위 테스트를 작성했습니다.
그것만으로는 충분하지 않습니다.
테스트 검증기는 오직 한 가지만 합니다: 기능이 사용자 스토리가 말한 대로 실제로 작동한다는 것을 증명하는 것.
승인 테스트를 작성합니다.
단위 테스트가 아닙니다.
승인 테스트입니다.
이 테스트는 기능을 외부에서 테스트합니다 — 실제 사용자가 경험하는 방식으로.
입력으로 받는 것: → 승인된 사용자 스토리 (모든 승인 기준 포함) → 승인된 기술 브리프 → 두 빌더의 요약
생성하는 것: → 모든 승인 기준을 다루는 하나의 승인 테스트 파일 → 보고서: 통과한 기준, 실패한 기준, 깔끔하게 다룰 수 없는 기준
할 수 없는 일: → 백엔드 또는 프론트엔드 코드 수정 → 테스트 불가능한 기준에 대한 해결 방법 발명 → 기준이 실제로 다루어지지 않았는데 다루어졌다고 표시
테스트가 실패하면: 기능이 스토리를 충족하지 않습니다.
정확히 어떤 기준이 실패했는지 보고합니다.
코드를 패치하지 않습니다.
그것은 올바른 빌더에게 돌아갑니다.
도구: 읽기, 편집, 쓰기 (테스트 파일만), Bash.
규칙: 승인 테스트가 통과할 때까지 기능이 완성된 것이 아닙니다.
에이전트 7: 구현 검증기
이 에이전트는 다른 모든 사람이 놓친 모든 것을 잡아냅니다.
검증기는 현재 구현을 승인된 스토리 및 브리프와 비교하고 — 차이점을 보고합니다.
절대 아무것도 고치지 않습니다.
그냥 사실을 말할 뿐입니다.
매번 실행하는 모든 검사:
→ 스토리의 승인 기준 중 아직 구현되지 않은 것 → 테스트 범위가 없는 실패 경로 → 보안 문제: 누락된 인증 검사, 테넌트 격리 공백, 로그의 비밀, 클라이언트에게 노출된 원시 오류 → 합의된 범위를 벗어나 변경된 파일 → CLAUDE.md 또는 기존 코드와 일치하지 않는 패턴 → 기존 헬퍼를 재사용해야 하는 중복 로직 → 브리프에서 조용히 건너뛴 시간대 또는 멀티 테넌트 관련 사항
출력은 항상 심각도별로 그룹화됩니다:
심각 — 병합 전에 반드시 수정 중요 — 병합 전에 수정 권장 경미 — 의견 기반, 리뷰어 판단
모든 발견 사항에는 파일 경로와 라인 번호가 포함됩니다.
잘못된 것이 없으면, 그렇게 명확히 말합니다.
철저해 보이기 위해 문제를 발명하지 않습니다.
도구: 읽기, Grep, Glob만.
이 에이전트가 팩토리를 신뢰할 수 있게 만드는 이유입니다.
자가 채점된 성적표는 가치가 없습니다.
디스크에 있는 것만 보고 — 어떻게 작성되었는지는 보지 않는 검증기는 정직합니다.
체인이 실행되는 방식
전체 흐름 — 하나의 프롬프트로 모든 것이 시작됩니다:
Claude Code를 열고 다음과 같이 입력합니다:
"7일 이상 미납된 인보이스에 대한 인보이스 알림을 구축해 줘."
다른 것을 입력하지 않고도 일어나는 일:
1단계 → 리서처가 인보이스, 지불 및 이메일 코드를 매핑합니다. 관련 파일, 기존 패턴, 위험 요소를 반환합니다.
2단계 → 스토리 라이터가 사용자 스토리와 승인 기준을 생성합니다.
⏸ 일시 중지: 스토리를 읽고 승인합니다.
3단계 → 스펙 라이터가 승인된 스토리를 기술 브리프로 전환합니다.
⏸ 일시 중지: 브리프를 읽고 승인합니다.("메모리에 ID 저장" 실수를 바로 여기서 잡으세요.)
4단계 → 백엔드 빌더가 서비스, API 라우트, BullMQ 작업 및 단위 테스트를 구현합니다. 반환: 변경된 파일, 재사용된 패턴, 모든 테스트 통과.
5단계 → 프론트엔드 빌더가 백엔드 빌더의 API 요약을 읽고, 관리 UI 타일과 알림 버튼을 구축하고, 컴포넌트 테스트를 작성합니다. 모든 테스트 통과.
6단계 → 테스트 검증기가 6개의 모든 승인 기준에 대한 승인 테스트를 작성합니다. 보고: 7개 통과, 1개 실패 — 수동 트리거가 테넌트 소유권을 확인하지 않음.
7단계 → 검증기가 이를 발견합니다. 파일 경로와 라인 번호와 함께 심각으로 보고합니다.
→ 백엔드 빌더로 루프백. 수정 적용. 8개의 모든 승인 테스트 통과. 검증기 다시 실행. 깨끗함.
⏸ 일시 중지: 검토하고 PR을 엽니다.
세 번의 인간 체크포인트.
다른 모든 것은 스스로 실행됩니다.
기초: 에이전트가 작동하기 전에 이것이 필요합니다
CLAUDE.md — 모든 세션을 유지하는 메모리:
Claude Code를 열 때마다, 제로 메모리로 시작합니다.
CLAUDE.md가 이를 해결합니다.
매 세션마다 자동으로 로드되는 리포지토리 루트의 Markdown 파일입니다.
영구적인 프로젝트 사실이 있는 곳:
→ 스택 (Next.js App Router, Node.js, Prisma, BullMQ, Resend) → 명령어 (npm run dev, npm test, npx prisma migrate dev) → 아키텍처 규칙 ("비즈니스 로직은 서비스에 있습니다. API 라우트는 얇게 유지합니다.") → 하지 말아야 할 것 ("cron을 추가하지 마세요 — BullMQ를 사용하세요. 원시 지불 페이로드를 기록하지 마세요.") → 더 깊은 문서への 포인터 (docs/billing.md, docs/architecture.md)
100-300줄로 유지하세요.
AI가 놀라게 하는 실수를 할 때마다, CLAUDE.md의 규칙이 이를 방지할 수 있었을까? 자문해 보세요.
규칙을 추가하세요.
몇 주 안에, CLAUDE.md는 AI가 잘못 이해한 모든 가정의 기록이 되고 — 세션이 눈에 띄게 좋아집니다.
컨텍스트 드리프트 — 조용한 킬러:
대부분의 Claude Code 세션은 극적으로 실패하지 않습니다.
그들은 표류합니다.
잘못된 가정이 컨텍스트에 들어옵니다.
모델이 그 위에 계속 구축합니다.
Claude에게 구독 관리를 구축해 달라고 요청합니다.
설계: 사용자 → 구독.
당신은 기억합니다: 구독은 사용자가 아니라 회사에 속한다는 것을.
"아니요, 구독은 회사에 속합니다"라고만 말하면 — Claude가 패치합니다.
이제 user.subscriptionId와 company.subscriptionId가 모두 떠다니게 됩니다.
규칙:
→ 작은 오타? 인라인으로 수정하세요. → 잘못된 아키텍처 가정? 대화를 버리고 올바른 가정을 첫 번째 프롬프트에 넣어 새로 시작하세요.
올바른 멘탈 모델을 가진 깨끗한 세션이 패치된 세션을 항상 이깁니다.
결과: 실제로 바뀌는 것
팩토리 전:
→ 바이브 코딩 루프: 프롬프트 → 생성 → 에러 → 패치 → 반복 → 세션 컨텍스트가 노이즈로 가득 참 → 잘못된 가정이 망가진 기능으로 이어짐 → 한 명의 엔지니어가 한 번에 한 가지만 할 수 있음 → 모든 기능이 적절한 사람이 가능할 때까지 기다림
팩토리 후:
→ 구조화된 체인: 리서치 → 스토리 → 브리프 → 구축 → 검증 → 확인 → 각 에이전트가 필요한 것만 있는 깨끗한 컨텍스트 윈도우를 얻음 → 잘못된 가정이 10개 파일 이후가 아니라 브리프 승인에서 잡힘 → 한 명의 엔지니어가 완전한 수직 조각을 제공: 백엔드, 프론트엔드, 테스트, 검증 → 팀의 최고 지식이 사람에게 갇히지 않고 에이전트에 살게 됨
진정한 변화:
결제 전문가가 결제 통합 에이전트를 구축합니다.
이제 팀의 모든 엔지니어가 청구를 건드리는 기능을 제공할 수 있습니다.
기다리지 않고.
인계 없이.
프론트엔드 리드의 컴포넌트 패턴이 프론트엔드 빌더 에이전트에 살게 됩니다.
DevOps 엔지니어의 CI 검사가 훅에 살게 됩니다.
QA 리드의 예외 케이스가 테스트 검증기 규칙에 살게 됩니다.
전문가 지식, 에이전트로 공유.
가용성에 갇히지 않음.
이번 주말에 직접 구축하는 방법
8단계 설정 체크리스트:
1. Claude Code 설치 → code.claude.com
2. 폴더 구조 생성: → .claude/agents/ → .claude/skills/feature-factory/ → .claude/skills/build-with-tests/ → .claude/hooks/
3. CLAUDE.md 작성 (100-300줄: 스택, 명령어, 아키텍처 규칙, 하지 말아야 할 목록)
4. Claude Code에서 /agents 명령어를 사용하여 7개의 에이전트를 생성합니다. 각 에이전트의 역할을 설명합니다. Claude가 파일을 작성합니다. 검토하고 커밋합니다.
5. feature-factory 오케스트레이터 스킬을 생성합니다. Claude에게 작성해 달라고 요청하세요 — 7개의 에이전트 파일을 읽고 체인을 연결합니다.
6. build-with-tests 스킬을 생성합니다. 팀이 어떻게 구축하는지 설명합니다: 기존 패턴과 일치시키고, 코드와 함께 테스트를 작성하고, 마지막에 타입체크를 실행합니다.
7. 사전 커밋 훅을 추가합니다. .env, .key, .pem 또는 secrets.json 파일을 포함하는 커밋을 차단합니다. 5분이면 됩니다. 재앙을 방지합니다.
8. 하나의 실제 기능을 전체 체인을 통해 실행합니다. 작은 것을 선택하세요. 어디서 막히는지 지켜보세요. 규칙을 추가하세요. 팩토리가 스스로 조정됩니다.
총 시간: 2-3시간.
그런 다음 몇 가지 기능을 실행하세요.
3-4번 후에는 팩토리가 코드베이스를 알게 됩니다.
감독에 시간을 덜 쓰게 됩니다.
다음에 무엇을 구축할지 결정하는 데 더 많은 시간을 쓰게 됩니다.
7가지 에이전트 — 빠른 참조
→ 리서처 — 아무것도 구축되기 전에 코드를 매핑 (읽기만) → 스토리 라이터 — 아이디어를 승인 기준이 있는 사용자 스토리로 전환 (읽기만) → 스펙 라이터 — 스토리를 기술 브리프로 전환 (읽기만) → 백엔드 빌더 — API, 서비스, 작업, 단위 테스트 구축 (백엔드 폴더만) → 프론트엔드 빌더 — 컴포넌트, 페이지, 훅, UI 테스트 구축 (프론트엔드 폴더만) → 테스트 검증기 — 사용자 스토리에 대한 승인 테스트 작성 (테스트 파일만) → 검증기 — 구현을 스토리 및 브리프와 비교, 차이점 보고 (읽기만)
3개의 인간 체크포인트:→ 스토리 승인 → 브리프 승인 → PR 승인
다른 모든 것은 스스로 실행됩니다.
Claude Code를 사용하는 대부분의 개발자는 여전히 바이브 코딩을 하고 있습니다.
프롬프트 → 생성 → 패치 → 희망.
그게 틀렸다는 말이 아닙니다.
그냥 한계가 있을 뿐입니다.
팩토리는 당신을 프로세스에서 제거하지 않습니다.
당신이 필요하지 않은 부분에서 당신을 제거합니다.
당신의 판단이 중요한 루프에 남아 있습니다:
이것이 올바른 문제인가? 이것이 올바른 설계인가? 이것이 출시하기에 안전한가?
에이전트는 그 사이의 모든 것을 처리합니다.
그것이 AI를 더 빠른 키보드로 사용하는 것과 —
AI를 조정된 팀으로 사용하는 것의 차이입니다.
이것이 유용했다면:
→ 네트워크와 공유하려면 리포스트 → 더 많은 분석을 보려면 @sairahul1 팔로우 → 북마크 — 7가지 에이전트를 참조하고 싶을 것입니다
저는 AI, 제품 구축, 당신이 잠자는 동안 작동하는 시스템에 대해 씁니다.
