03. Ryan Carson의 3-파일 시스템

Ryan Carson의 3-파일 시스템 

AI 코딩을 “빠른 프로토타이핑”에서 끝내지 않고, 일관된 품질·테스트·유지보수 가능성까지 갖춘 프로덕션 개발 프로세스로 끌어올리는 방법이 바로 Ryan Carson의 3-파일 시스템입니다.
핵심은 단순합니다.

• 무엇을 만들지를 PRD로 고정하고
• 무엇을 먼저 할지를 작업으로 쪼개고
• 어떻게 안전하게 완성할지를 TDD로 보장합니다.

---

“Ryan Carson의 3-파일 시스템”

요약

• “3-파일 시스템”을 AI 기반 개발을 안정적인 워크플로우로 만드는 방법론으로 소개합니다. 즉, AI로 코드를 ‘생성’하는 것에 멈추지 않고, 개발 전체 흐름을 구조화해서 결과 품질을 일정하게 만들자는 선언입니다.

핵심 포인트

• AI 코딩은 강력하지만, 프로세스 없이 쓰면 결과가 흔들리기 쉽다
• 3-파일 시스템은 그 흔들림을 문서(파일)로 고정해서 줄인다

---

Part 1 — 혼돈 속 질서: AI 코딩의 새로운 패러다임

요약

• AI 코딩 도구가 아무리 좋아져도, 실무에서는 “그때그때 생성 → 그때그때 수정”으로는 안정적인 개발이 어렵습니다. 그 이유를 전제로, 3-파일 시스템을 혼돈(즉흥적인 AI 생성) 속에서 **질서(반복 가능한 프로세스)**를 만드는 방식으로 제시합니다.

핵심 포인트

• AI 코딩을 실전에서 쓰려면 워크플로우가 필요하다
• 3-파일 시스템은 그 워크플로우를 최소 단위로 정리한 구조다

---

AI 코딩의 문제점 vs 3-파일 시스템의 해법

요약

• “왜 3-파일 시스템이 필요한가”를 가장 명확하게 보여줍니다. AI 코딩이 실패하는 전형적인 원인을 나열하고, 그에 대응하는 해결책을 “파일로 고정된 개발 단계”로 제시합니다.

AI 코딩의 대표 문제

• 코드 품질이 일관되지 않음
• 에러 핸들링이 불완전해지기 쉬움
• 테스트가 빠져 불안정해짐
• 문서화가 약해져 유지보수/확장성이 떨어짐

3-파일 시스템의 해결책

• 명확한 요구사항 정의(PRD)
• 체계적인 작업 분해(Tasks)
• TDD 통합으로 품질 보장(Process)
• 같은 방식으로 반복 가능한 표준 워크플로우 확보

---

3-파일 시스템 개요 — 세 파일이 하는 일

요약

• 3-파일 시스템은 개발을 아래 3단계로 단순화합니다. 각 단계는 “다음 단계가 흔들리지 않도록” 앞 단계 결과물을 문서로 고정합니다.

01) create-prd.md — 요구사항(PRD)을 고정한다

• 프로젝트 목표, 범위, 성공 기준을 문서로 고정
• AI가 구현 과정에서 임의로 방향을 바꾸지 못하도록 나침반 역할을 합니다.

02) generate-tasks.md — PRD를 실행 단위로 쪼갠다

• PRD를 실제로 실행 가능한 작은 작업들로 분해
• 작업을 부모–자식 구조로 만들고, 순서를 설계합니다.

03) process-task-list.md — 작업을 TDD로 끝낸다

• 각 작업을 수행할 때 테스트를 먼저 작성하고, 통과를 기준으로 완료 처리
• 결과적으로 “돌아가는 코드”가 아니라 검증된 코드를 쌓습니다.

핵심 포인트

• 이 구조는 “Planning → Development → Deployment”로 이어지는 흐름을 끊지 않고,
• 문서-작업-검증을 한 파이프라인으로 연결합니다.

---

Part 2 — 각 파일 심층 분석

요약

• “이제부터는 3개 파일을 하나씩 자세히 본다”는 전환점입니다.
• 중요한 포인트는 “각 파일이 단독으로 중요한 게 아니라, 연결될 때 시너지가 난다”는 점입니다.

핵심 포인트

• PRD만 잘 써도 부족하고, Tasks만 잘 나눠도 부족합니다.
• 세 파일이 순서대로 연결될 때 AI 개발이 안정화됩니다.

---

create-prd.md — AI가 만드는 PRD(제품 요구사항)

요약

• 좋은 PRD는 “문서”가 아니라 AI가 안정적으로 개발하도록 만드는 입력값입니다. PRD의 핵심 구성요소 3가지를 제시합니다.

1) 명확한 목표 설정

• 프로젝트 비전/목표/성공 지표를 구체화합니다.
• “좋게 만들자”가 아니라 측정 가능한 기준이 들어가야 합니다.

2) 사용자 스토리

• 사용자 관점으로 “무엇을 왜 필요로 하는지”를 고정합니다.
• 기능 목록이 아니라 사용 목적(가치) 중심으로 정리합니다.

3) 기술 요구사항

• 기술 스택, 아키텍처, 성능/보안 같은 제약을 문서에 명시합니다.
• AI가 구현 중 임의의 기술 선택을 하거나 일관성이 깨지는 것을 방지합니다.

정리

• PRD 템플릿을 사용하면 놓치기 쉬운 요구사항(엣지 케이스, 제약, 성공 기준)을 체계적으로 담을 수 있고,
• 이 PRD가 이후 Tasks와 TDD까지의 품질을 결정합니다.

---

generate-tasks.md — PRD를 “작업”으로 분해한다

요약

• AI에게 일을 잘 시키는 핵심은 “큰 요구를 작은 작업으로 분해하는 것”입니다. 작업 분해의 기준과 구조를 제시합니다.

작업 분해 원칙

• 각 작업은 30분 ~ 2시간 안에 끝낼 수 있는 크기
• 작업마다 **명확한 입력/출력(완료 기준)**이 있어야 합니다.

1) 부모 작업 정의

• 큰 기능 단위를 먼저 정의합니다.
  예: “사용자 인증 시스템 구축”

2) 자식 작업 생성

• 구현 가능한 단위로 쪼갭니다.
  예: “로그인 API 엔드포인트 생성”, “JWT 토큰 검증 미들웨어 구현”

3) 의존성 관리

• 어떤 작업이 먼저 끝나야 다음 작업이 가능한지 순서를 명확히 합니다.
• 이 순서가 깨지면 구현이 꼬이고, AI 결과도 흔들립니다.

정리

• 작업이 작을수록 AI는 정확해지고, 결과는 안정적입니다.
• 결국 “큰 문제를 작은 문제로 쪼개서 해결”하는 원리를 개발 프로세스에 그대로 적용합니다.

---

process-task-list.md — TDD로 안정성을 고정한다

요약
3-파일 시스템의 “품질 보증 장치”를 설명합니다. 작업을 진행할 때마다 TDD 루프를 돌려서, 마지막에 몰아서 디버깅하지 않도록 설계합니다.

1) 테스트 먼저 작성

• “기대 동작”을 테스트로 정의합니다.
• 완료 기준이 코드가 아니라 테스트 통과로 고정됩니다.

2) 최소 기능 구현

• 테스트를 통과시키는 최소 구현을 합니다.
• 과도한 구현을 줄이고, 목표 기능에 집중합니다.

3) 리팩터링 및 최적화

• 테스트가 보장해주는 안전망 위에서 코드 품질을 올립니다.
• 중복 제거, 구조 개선, 성능 개선을 진행합니다.

4) 다음 작업으로 이동

• 테스트가 모두 통과한 상태에서만 다음 작업으로 넘어갑니다.
• 누적 버그를 줄이고, 전체 안정성을 유지합니다.

정리

• 이 구조는 “프로젝트 끝나고 버그 잡기”가 아니라,
• 작업 단위로 즉시 검증해서 디버깅 비용을 크게 줄입니다.

---

적용 팁 — 실제로 굴릴 때 지켜야 할 원칙

요약
3-파일 시스템을 제대로 적용하기 위한 운영 원칙을 정리합니다. 실제 적용에서 흔들리는 지점을 직접 겨냥합니다.

1) 충분한 맥락 제공

• AI에게 프로젝트 배경/제약/기술 스택을 충분히 제공해야 결과가 안정적입니다.

2) 명확하고 구체적인 PRD

• “사용자 친화적” 같은 말 대신,
• “3번 클릭 이내 결제 완료”처럼 측정 가능한 기준으로 작성합니다.

3) 작업은 작게, 테스트는 꼼꼼히

• 큰 작업은 더 쪼개고,
• 모든 작업은 테스트로 완료 기준을 고정합니다.

4) 어떤 AI 도구와도 통합 가능

• Cursor, GitHub Copilot, Claude Code, Codex 등 도구가 무엇이든,
• 핵심은 도구가 아니라 프로세스입니다.

최종 결론

• 처음에는 느려 보이지만, 시간이 갈수록 더 빠르고 안정적입니다.
• 익숙해지면 “속도”와 “품질”을 동시에 가져가게 됩니다.