한 줄 프롬프트로 프로젝트를 생성하는 Project Factory 설계

"프리랜서 실수령액 계산기 만들어줘" 한 줄로 저장소, 코드, 테스트, 배포까지 끝나는 흐름을 Project Factory라고 부르자. 에이전트에게 그냥 시키면 매번 다른 구조, 빠진 테스트, 확인 안 된 배포가 나온다. 공장처럼 같은 품질로 찍어 내려면 해석, 명세, 템플릿, 구현 루프, 검증 게이트, 배포를 단계로 나누고 단계마다 끝 기준을 둬야 한다. 이 글은 Claude Code의 Skill, 서브에이전트, Hook으로 그 구조를 설계하는 방법을 정리한 것이다.

한 장의 메모 카드가 컨베이어 입구로 들어가 설계도, 틀, 조립, 검수를 거쳐 끝에서 깃발 꽂힌 작은 건물이 되는 공장

전체 흐름

단계	입력	출력	끝 기준
1. 해석	한 줄 프롬프트	유형·기능·제약	기본값으로 빈칸을 다 채웠다
2. 명세	해석 결과	`SPEC.md`	기능 3~5개, 완료 기준, 범위 밖 항목이 있다
3. 템플릿·스캐폴드	명세	실행되는 빈 프로젝트	`verify`가 빈 상태에서 통과한다
4. 구현 루프	명세, 프로젝트	기능 코드와 테스트	기능마다 checker PASS
5. 검증 게이트	완성 코드	판정	`verify` 전체 통과, 완료 기준 충족
6. 배포·보고	통과한 코드	URL, 보고서	배포 주소가 응답하고 남은 일이 적혀 있다

한 줄 프롬프트가 해석·명세, 템플릿 카탈로그에서 고른 스캐폴드, maker·checker 구현 루프, 검증 게이트를 거쳐 배포·보고로 이어지고, 검증에 실패하면 구현 루프로 되돌아가며 배포 전에는 사람이 확인하는 Project Factory 흐름

1단계: 해석은 질문 대신 기본값으로

한 줄 프롬프트에는 정보가 거의 없다. 매번 사용자에게 되물으면 "한 줄"의 의미가 사라진다. 그래서 공장은 빈칸을 기본값 표로 채우고, 정말 갈리는 것만 하나 묻는다.

항목	기본값	묻는 경우
유형	웹앱	프롬프트에 CLI·API·봇이 나오면 그 유형
스택	카탈로그의 기본 템플릿	사용자가 스택을 지정하면
데이터	로컬 SQLite	여러 사용자가 같은 데이터를 써야 하면
인증	없음	개인 데이터가 있으면 질문 1개
배포	미리보기 배포	운영 배포는 사람 확인 뒤

기본값은 Skill 본문 첫머리에 표로 둔다. 모델이 표를 보고 판단하므로, 기본값을 바꾸고 싶을 때 코드가 아니라 표를 고치면 된다.

2단계: 명세는 범위 밖까지 적는다

명세가 없으면 구현 루프가 끝나지 않는다. 에이전트는 "있으면 좋을 기능"을 계속 붙이기 때문이다. SPEC.md에는 반드시 범위 밖 항목과 완료 기준을 넣는다.

# SPEC: 프리랜서 실수령액 계산기

목표: 계약 금액을 넣으면 세금(3.3%)과 4대 보험 선택을 반영한 실수령액을 보여 준다.
사용자: 처음 계약하는 프리랜서. 모바일에서 주로 본다.

기능
1. 금액 입력 → 실수령액 즉시 계산
2. 원천징수·보험 항목별 내역 표시
3. 결과를 링크로 공유(입력값을 URL에)

비기능: 첫 화면 2초 안에 표시, 375px 폭에서 가로 스크롤 없음
범위 밖: 로그인, 결과 저장, 관리자 화면, 결제
완료 기준: 계산 함수 단위 테스트 통과, verify 통과, 미리보기 URL에서 세 기능 동작

명세는 사람에게 보여 주는 첫 산출물이기도 하다. 방향이 틀렸으면 여기서 멈추는 게 가장 싸다.

3단계: 템플릿 카탈로그와 결정적 스캐폴드

빈 프로젝트를 모델이 매번 새로 만들면 폴더 구조, 린트, 테스트 설정이 매번 달라진다. 검증된 템플릿을 카탈로그로 두고, 복사는 스크립트가 한다.

# factory/templates.yaml
- id: web-sveltekit-sqlite
  when: 웹앱, 데이터 저장 필요, 기본
  source: templates/web-sveltekit-sqlite
  verify: npm run verify        # check → test → build
- id: web-static
  when: 계산기·소개 페이지처럼 서버 데이터가 없는 웹
  source: templates/web-static
  verify: npm run verify
- id: api-fastapi
  when: API만 필요, 파이썬 지정
  source: templates/api-fastapi
  verify: make verify

템플릿마다 같이 들어 있어야 하는 것:

CLAUDE.md: 명령어, 구조, "완료 = verify 통과" 규칙
verify 명령: 타입 검사 → 테스트 → 빌드 순서로, 처음 실패에서 멈춘다
샘플 테스트 하나: 구현 루프가 테스트를 어디에 어떻게 쓸지 따라 하게 한다
배포 설정: 미리보기 배포가 바로 되는 상태

스캐폴드 단계의 끝 기준은 빈 프로젝트에서 verify가 통과하는 것이다. 여기서 실패하면 템플릿 문제이므로 구현을 시작하지 않는다.

4단계: 구현은 maker–checker 루프로

기능 하나를 한 단위로 돌린다.

maker 에이전트: 명세의 기능 하나를 구현하고 테스트를 함께 쓴다. 자기 결과를 검수됐다고 말하지 않는다.
checker 에이전트: 수정 도구 없이(tools: Bash, Read, Grep, Glob) verify를 실행하고, 명세의 해당 기능과 코드를 대조해 PASS/FAIL과 고칠 위치를 보고한다.
오케스트레이터: FAIL이면 같은 maker에게 지적 항목만 넘긴다. 기능당 최대 3번, 그래도 FAIL이면 멈추고 사람에게 보고한다.

기능 단위로 나누는 이유는 실패 범위를 줄이기 위해서다. 세 기능을 한 번에 만들고 검수하면 어느 기능이 무엇을 깨뜨렸는지 찾는 데 루프를 다 쓴다.

5단계: 검증 게이트는 Hook으로 강제한다

"끝나면 verify 돌려"를 Skill에만 적어 두면 모델이 건너뛰는 날이 온다. 공장의 게이트는 Hook과 명령으로 강제한다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "factory/hooks/require-verify.sh" }]
      }
    ]
  }
}

require-verify.sh는 실행하려는 명령이 배포(vercel deploy 등)일 때만 직전 verify 결과 파일을 확인하고, 없거나 실패면 종료 코드 2로 막으며 "먼저 npm run verify를 통과시킬 것"이라고 출력한다. 배포가 아닌 명령은 그대로 통과시킨다. 이렇게 하면 모델이 아무리 서둘러도 검증 없이 배포되는 길이 없다.

게이트에서 함께 확인할 것:

verify 전체 통과(타입, 테스트, 빌드)
명세의 완료 기준 항목을 하나씩 체크
비밀값이 코드나 설정에 들어가지 않았는지 검사

6단계: 배포와 보고, 그리고 사람이 확인하는 자리

미리보기 배포까지는 자동으로 한다. 운영 배포, 도메인 연결, 결제·외부 계정 생성처럼 되돌리기 어렵거나 돈이 드는 일은 사람이 확인한 뒤에만 한다.

보고서는 짧게 고정된 형식으로 남긴다.

프로젝트: freelancer-calculator
미리보기: https://…
명세 기능: 3/3 (각 checker PASS)
verify: check 0 errors · Tests 12 passed · build OK
범위 밖으로 둔 것: 로그인, 결과 저장
확인하지 못한 것: 실제 휴대폰 기기 테스트
다음 결정: 운영 배포 여부

공장을 지키는 안전장치

위험	장치
범위가 끝없이 커진다	명세의 범위 밖 항목, 기능 단위 루프
무한 루프로 비용이 샌다	기능당 루프 3회, 전체 시간·토큰 상한
검증 없이 배포된다	배포 명령 앞 `PreToolUse` Hook
위험한 명령 실행	권한 설정과 차단 Hook(`rm -rf`, 강제 푸시 등)
비밀값 유출	템플릿의 `.env.example`, 게이트의 비밀값 검사
매번 다른 구조	템플릿 카탈로그와 스크립트 스캐폴드

자주 하는 실수

명세 없이 바로 코드를 쓴다. 구현 루프에 끝 기준이 없어 기능이 계속 늘어난다.
스캐폴드를 모델에게 맡긴다. 프로젝트마다 구조와 설정이 달라져 공장이 아니라 수공업이 된다.
빈 프로젝트의 verify를 확인하지 않는다. 템플릿 문제를 구현 문제로 착각하고 루프를 낭비한다.
검증 규칙을 Skill 문장으로만 둔다. 강제가 필요한 규칙은 Hook으로 보낸다.
운영 배포까지 자동으로 한다. 되돌리기 어려운 일은 사람이 확인하는 자리를 남긴다.

점검표

해석 단계의 기본값 표가 있고, 질문은 최대 1개다
SPEC.md에 기능, 비기능, 범위 밖, 완료 기준이 있다
템플릿 카탈로그가 있고 스캐폴드는 스크립트가 한다
템플릿마다 CLAUDE.md, verify, 샘플 테스트, 배포 설정이 있다
빈 프로젝트에서 verify가 통과한 뒤 구현을 시작한다
구현은 기능 단위 maker–checker 루프이고 최대 횟수가 있다
배포 명령 앞에서 Hook이 verify 결과를 확인한다
운영 배포·결제·외부 계정은 사람 확인 뒤에만 한다
보고서에 검증 결과, 범위 밖, 확인하지 못한 것이 있다

Project Factory의 핵심은 한 줄 프롬프트를 똑똑하게 해석하는 데 있지 않다. 기본값, 명세, 템플릿, 루프, 게이트를 미리 정해 두어 누가 몇 번을 돌려도 같은 품질이 나오게 하는 데 있다.