deep-project: 요구사항을 아주 제대로 정의해보자

AI 코딩 도구를 쓰다 보면, 가장 먼저 부딪히는 문제는 코드 생성 자체가 아닙니다.
오히려 “무엇을 어디까지 만들 것인가”를 구조화하지 못한 상태에서 너무 큰 요구사항을 한 번에 던지는 일이 더 큰 문제입니다.
예를 들어 “SaaS 플랫폼 하나 만들어줘” 같은 요청은 그럴듯해 보이지만, 실제 구현 단계로 내려가면 인증, 결제, 대시보드, 외부 연동처럼 서로 다른 성격의 하위 문제들이 섞여 있습니다. (GitHub)

deep-project는 바로 이 지점을 다룹니다.
이 도구는 모호하고 큰 프로젝트 요구사항을 바로 구현하려 하지 않고, 먼저 인터뷰와 분해 과정을 거쳐 “계획 가능한 단위”로 나누는 데 집중합니다.

GitHub - piercelamb/deep-project: Claude Code plugin that transforms vague software ideas into individual, ready-to-be-planned c

 

왜 이 문제가 중요한가

프로젝트 요구사항이 큰데도 바로 설계나 구현으로 들어가면, 가장 먼저 비용 문제가 생깁니다.
같은 내용을 여러 번 다시 설명해야 하고, 각 세션마다 컨텍스트를 다시 쌓아야 하며, 잘못 쪼개진 작업 때문에 재계획이 반복됩니다.
결국 API 비용이든, 사람의 검토 비용이든, 둘 다 늘어납니다. 이는 README가 말하는 “인터뷰에 약 15분 투자하고 이후 재작업 시간을 줄인다”는 메시지와도 맞닿아 있습니다. (GitHub)

성능 문제도 큽니다.
하나의 거대한 요구사항 안에는 독립적으로 판단해야 할 서브시스템이 여러 개 들어 있는데, 이를 한 번에 처리하면 모델이 범위를 과도하게 넓게 해석하거나, 중요한 관계를 놓치기 쉽습니다.
README에서도 이런 경우 Claude가 범위에 압도되어 가정을 늘리고, 통합 이슈와 재작업으로 이어질 수 있다고 설명합니다. (GitHub)

유지보수 문제는 더 실무적입니다.
처음부터 기능 경계가 정리되지 않으면, 나중에 문서와 구현 단위가 엉키고, 어떤 컴포넌트가 무엇에 의존하는지 추적하기 어려워집니다.
특히 인증, 결제, 관리자 기능처럼 순서와 의존성이 중요한 영역은 초기에 구조를 잘못 잡으면 이후 수정 비용이 크게 올라갑니다. deep-project가 manifest와 dependency mapping을 별도로 두는 이유가 여기에 있습니다. (GitHub)

개발 경험 측면에서도 손실이 큽니다.
거대한 요구사항을 한 번에 처리하면 디버깅이 어려워지고, 세션이 끊겼을 때 어디까지 진행했는지 복원하기도 힘듭니다.
반대로 deep-project는 인터뷰 기록, 분해 결과, 디렉터리 생성, 스펙 생성 상태를 기준으로 재개 지점을 판단하도록 설계되어 있습니다. 이건 단순 편의 기능이 아니라, AI 기반 작업 흐름을 끊김 없이 유지하기 위한 핵심 설계입니다. (GitHub)

deep-project란 무엇인가

deep-project는 모호한 프로젝트 요구사항을 잘 계획할 수 있는 여러 개의 작업 단위로 분해해 주는 Claude Code 플러그인입니다. (GitHub)

비유하자면, 바로 집을 짓는 도구가 아니라 먼저 방 개수, 배관, 전기, 출입 동선부터 나눠서 설계 도면의 뼈대를 만드는 도구에 가깝습니다.
즉, “만들기”보다 먼저 “어떻게 나눌지”를 결정하는 단계에 특화되어 있습니다. (GitHub)

기술적으로 보면 이 도구는 큰 요구사항을 입력받아 인터뷰를 수행하고, 분할이 필요한지 판단한 뒤, 각 분할 단위의 의존 관계와 실행 순서를 정리한 manifest와 개별 spec.md 파일들을 생성합니다.
이 출력물은 이후 deep-plan 같은 다음 단계 도구에 넘겨 더 세밀한 구현 계획으로 이어지도록 설계되어 있습니다. 즉, 구현 도구가 아니라 “계획 전처리기”에 가깝습니다. (GitHub)

기존 방식과의 차이는 분명합니다.
보통은 하나의 긴 프롬프트로 전체 시스템을 설명하고, 그 결과를 다시 사람이 정리합니다.
반면 deep-project는 처음부터 요구사항 분해를 독립된 단계로 분리합니다. 철학적으로도 “큰 문제를 바로 풀지 말고, 먼저 경계를 정의하라”에 가깝습니다. (GitHub)

핵심 특징

• AI 인터뷰 기반 요구사항 보완
  입력 파일이 대충 적혀 있어도 인터뷰 단계에서 사용자의 머릿속 구조를 끌어냅니다. 그래서 처음부터 완벽한 명세를 써두지 않아도 됩니다. (GitHub)
• 프로젝트 분할 여부를 먼저 판단
  무조건 여러 개로 쪼개는 것이 아니라, 이 프로젝트가 정말 분할이 필요한지부터 평가합니다. 작은 기능이면 단일 단위로 유지할 수도 있습니다. (GitHub)
• 의존 관계와 실행 순서를 문서화
  단순히 파일만 여러 개 만드는 것이 아니라, 어떤 단위가 무엇에 선행하는지 manifest에 남깁니다. 이게 있어야 이후 계획과 구현이 덜 흔들립니다. (GitHub)
• 재개 가능한 워크플로우
  세션이 끊기거나 중단돼도 기존 산출물을 보고 어디서부터 이어갈지 판단합니다. AI 도구를 실무에서 쓸 때 중요한 안정성을 의식한 구조입니다. (GitHub)
• 출력물이 다음 단계 도구와 자연스럽게 연결됨
  각 분할 디렉터리 안의 spec.md는 이후 deep-plan에 넘기기 위한 입력으로 설계되어 있습니다. 즉, 독립 도구라기보다 파이프라인의 첫 단계입니다. (GitHub)
• 외부 API 키 없이 동작
  README 기준으로 Python 의존성만 관리하면 되고, deep-plan과 달리 외부 API 키가 필요하지 않다고 설명합니다. 초기 진입 장벽이 낮다는 뜻입니다. (GitHub)

실제로 어떤 효과가 있는가

공개된 자료 기준으로 보면, 이 도구의 핵심 효과는 “큰 요구사항을 작은 계획 단위로 바꾸는 것”입니다.
예시로는 SaaS 플랫폼 같은 넓은 범위의 프로젝트를 인증, 결제, 대시보드 같은 식으로 분해해 각 단위를 별도 계획 세션으로 넘길 수 있게 합니다.
즉, 한 번에 모든 걸 잘하게 만드는 도구가 아니라, 한 번에 잘못 다루지 않게 만드는 도구입니다. (GitHub)

전과 후를 비교하면 차이가 분명합니다.
이전에는 하나의 넓은 요구사항을 통째로 처리하다 보니 범위가 뒤섞이고 관계가 누락되기 쉬웠습니다.
이후에는 인터뷰, 분할 분석, 의존성 정리, 스펙 생성까지 거치면서 각 작업 단위가 독립적으로 검토 가능한 형태로 바뀝니다. README는 이를 통해 수시간의 조정과 재작업을 줄일 수 있다고 설명합니다. (GitHub)

효과가 가장 큰 상황도 명확합니다.
여러 서브시스템이 얽힌 신규 프로젝트, 기능보다 제품 전체 구조가 먼저 필요한 프로젝트, 여러 계획 세션을 병렬로 나눠야 하는 팀에서 특히 유리합니다.
반대로 단일 기능이나 작은 버그 수정처럼 이미 범위가 좁은 일에는 효과가 제한적입니다. (GitHub)

특히 팀 단위 프로젝트에 잘 맞습니다.
manifest로 실행 순서와 의존성을 남기고, 각 split별 spec.md를 따로 만들기 때문에 사람이나 에이전트를 여러 갈래로 나누어 일시키기 쉬워집니다.
이 구조는 개인 생산성보다 협업 가능한 구조화에 더 큰 강점이 있습니다. (GitHub)

동작 원리 / 구조

1. 입력 파일 검증
   먼저 @path/to/requirements.md 형태의 요구사항 파일이 있는지, Markdown 파일인지, 비어 있지 않은지 검사합니다.
   이 단계가 있는 이유는 이후 흐름 전체가 파일 기반 상태 관리에 의존하기 때문입니다. 입력이 불안정하면 재개도 불가능해집니다. (GitHub)
2. 세션과 플러그인 루트 확인
   세션 시작 훅이 넣어준 DEEP_PLUGIN_ROOT, DEEP_SESSION_ID 같은 정보를 바탕으로 플러그인 루트와 세션 상태를 확인합니다.
   이건 단순 초기화가 아니라, 중단 후 재실행해도 같은 작업 목록과 상태를 복원하기 위한 장치입니다. (GitHub)
3. 인터뷰 수행
   고정된 질문지를 무조건 돌리는 방식이 아니라, 사용자의 답을 바탕으로 적응형 질문을 이어가며 프로젝트의 정신 모델을 끌어냅니다.
   왜 이런 방식이냐면, 처음 요구사항 문서는 대개 불완전하고, 실제로 중요한 분할 기준은 사용자의 머릿속에 있기 때문입니다. 인터뷰 결과는 별도 파일로 저장됩니다. (GitHub)
4. 분할 분석
   인터뷰 내용과 원본 요구사항을 바탕으로 이 프로젝트가 여러 planning unit으로 나뉘어야 하는지 판단합니다.
   중요한 점은 “항상 많이 쪼개는 것”이 아니라 “계획 가능한 단위로 쪼개는 것”입니다. 그래서 작은 기능이면 단일 단위로 유지할 수도 있습니다. (GitHub)
5. 의존성 발견과 manifest 생성
   각 split의 역할, 상호 관계, 추천 실행 순서를 project-manifest.md에 정리합니다.
   이 단계가 핵심인 이유는, 나누기만 하고 관계를 명시하지 않으면 이후 병렬 작업에서 다시 충돌이 생기기 때문입니다. README는 여기에 machine-readable한 SPLIT_MANIFEST 블록도 포함된다고 설명합니다. (GitHub)
6. 사용자 확인
   도구가 제안한 분해 구조를 바로 확정하지 않고, 사용자 승인 과정을 둡니다.
   이는 AI가 범위를 잘 쪼개는 것과, 실제 팀이 원하는 경계가 일치하는지를 마지막으로 맞추는 단계입니다. (GitHub)
7. 디렉터리 생성
   승인된 manifest를 바탕으로 번호가 붙은 split 디렉터리를 생성합니다.
   예를 들어 01-auth-system, 02-billing 같은 구조가 만들어집니다. 이 번호 체계는 순서를 눈에 보이게 하고, 후속 작업에서 경로 규칙을 단순하게 만들어 줍니다. (GitHub)
8. 각 split의 spec 생성
   마지막으로 각 디렉터리 안에 spec.md를 작성합니다.
   이렇게 생성된 스펙은 이후 더 깊은 계획 단계의 입력으로 쓰입니다. 즉, 결과물의 목적이 “문서 저장”이 아니라 “다음 자동화 단계의 안정적 입력”이라는 점이 중요합니다. (GitHub)

설치 / 사용 방법

현재 README 기준 기본 설치 흐름은 Claude Code 플러그인 마켓플레이스를 사용하는 방식입니다.
필수 조건으로는 Claude Code, Python 3.11 이상, uv가 제시되어 있습니다. (GitHub)

설치 명령어

/plugin marketplace add piercelamb/deep-project
/plugin install deep-project
/plugin enable deep-project

README에는 이미 같은 계열 플러그인을 추가한 경우, 마켓플레이스를 다시 추가하지 않고 설치만 진행할 수 있다고 안내합니다. (GitHub)

실행 흐름

먼저 planning 디렉터리에 요구사항 파일을 준비합니다.

mkdir -p planning

예를 들면 다음처럼 요구사항을 정리할 수 있습니다.

# My SaaS Platform

Build a complete SaaS platform with:
- User authentication
- Subscription billing
- Admin dashboard
- User-facing dashboard
- API for third-party integrations

이후 Claude Code에서 아래처럼 실행합니다.

/deep-project @planning/requirements.md

그다음에는 인터뷰 → 분할 분석 → 확인 → 생성 흐름으로 진행됩니다. (GitHub)

최소 실행 예제

mkdir -p planning
cat > planning/requirements.md << 'EOF'
# Internal Tool

Build an internal operations platform with:
- SSO login
- Role-based permissions
- Billing summary page
- Admin analytics
EOF

/deep-project @planning/requirements.md

실행이 끝나면 대략 다음과 같은 구조를 기대할 수 있습니다.

planning/
├── requirements.md
├── deep_project_interview.md
├── project-manifest.md
└── splits/
    ├── 01-auth-system/
    │   └── spec.md
    ├── 02-billing/
    │   └── spec.md
    └── 03-dashboard/
        └── spec.md

세션이 중간에 끊겨도 같은 명령을 다시 실행하면 기존 상태를 보고 재개할 수 있습니다. (GitHub)

자주 쓰는 예시 / 활용 시나리오

1. 여러 서브시스템이 섞인 신규 제품 기획

누가 봐도 범위가 넓은 SaaS, 내부 운영 플랫폼, B2B 제품 초기 기획에 적합합니다.
인증, 결제, 대시보드, API 연동처럼 결이 다른 문제를 먼저 갈라야 할 때 유용합니다. (GitHub)

2. deep-plan 같은 후속 계획 도구를 쓰기 전 단계

이미 spec 기반 계획 워크플로우를 운영하고 있다면, deep-project는 그 앞단에서 입력 품질을 정리하는 역할을 합니다.
특히 너무 큰 요구사항을 그대로 넣으면 후속 계획 단계도 흔들릴 수 있을 때 효과가 큽니다. (GitHub)

3. 팀 단위 병렬 계획

한 사람이 전체를 붙잡고 있기보다, split별로 각각 계획 세션을 따로 돌리고 싶은 경우에 적합합니다.
manifest에 의존성과 순서가 남기 때문에 누가 무엇을 먼저 해야 하는지 정리하기 쉽습니다. (GitHub)

4. AI 코딩 세션이 자주 끊기는 환경

컨텍스트 제한이나 세션 중단이 잦다면, 상태 기반 재개 기능이 큰 장점이 됩니다.
한 번의 긴 세션에 모든 걸 걸기보다, 단계별 산출물을 남기며 이어가는 방식에 맞습니다. (GitHub)

5. “무엇을 만들어야 하는지”부터 불명확한 프로젝트

요구사항 문서가 애매하고, 팀 내부에서도 경계가 합의되지 않은 경우에 특히 좋습니다.
인터뷰 단계가 바로 이런 애매함을 구조화하기 위한 장치입니다. (GitHub)

한계 / 주의할 점

문서상 확인되는 범위에서 보면, 이 도구는 어디까지나 분해와 계획 준비에 특화되어 있습니다.
즉, 이것만으로 상세 설계나 코드 구현이 끝나는 것은 아닙니다. 이후 단계 도구나 사람의 검토가 여전히 필요합니다. (GitHub)

현재 기준으로는 작은 작업에는 오히려 과할 수 있습니다.
README도 단일 기능, 버그 수정, 범위가 이미 명확한 작업이라면 건너뛰라고 안내합니다.
모든 문제를 무조건 잘게 쪼개는 것이 좋은 것은 아닙니다. (GitHub)

또 하나 주의할 점은, 분해 품질이 인터뷰 품질에 영향을 받는다는 것입니다.
도구가 자동으로 구조를 제안하더라도, 사용자가 프로젝트의 핵심 경계를 제대로 설명하지 못하면 결과도 어긋날 수 있습니다.
즉, 완전 자동화라기보다 “잘 질문하고 잘 정리하는 자동화”에 가깝습니다. (GitHub)

아직 검증되지 않은 영역도 있습니다.
공개 자료만으로는 대규모 조직에서 이 출력물이 얼마나 일관되게 유지되는지, 혹은 복잡한 도메인 모델에서 분해 기준이 얼마나 안정적인지까지는 확인하기 어렵습니다.
따라서 실무 적용 시에는 먼저 내부 프로젝트 한두 개에 시범 적용해 split granularity가 팀과 맞는지 확인하는 접근이 현실적입니다. 이는 공개된 문서 구조를 바탕으로 한 판단입니다. (GitHub)

마무리

deep-project의 핵심 가치는 코드를 더 빨리 쓰게 하는 데 있지 않습니다.
그보다 먼저, 큰 요구사항을 사람이 검토할 수 있고 다음 단계 도구가 다룰 수 있는 단위로 정리해 준다는 데 있습니다.
AI 코딩에서 가장 취약한 지점이 “모호한 입력”이라면, 이 도구는 바로 그 취약점을 줄이는 쪽에 서 있습니다. (GitHub)

특히 신규 제품을 설계하는 스타트업, AI 에이전트 기반 개발 워크플로우를 만들고 있는 개발자, 여러 서브시스템을 동시에 다뤄야 하는 팀에게 잘 맞습니다.
반대로 범위가 이미 분명한 작은 기능 작업에는 굳이 앞단 분해 단계를 넣지 않아도 됩니다. (GitHub)

핵심 요약

• 핵심 개념
  deep-project는 큰 요구사항을 인터뷰와 분해 과정을 통해 계획 가능한 단위로 나누는 Claude Code 플러그인입니다. (GitHub)
• 차별점
  바로 구현하지 않고, 먼저 split 구조와 의존성을 정리한 manifest 및 개별 spec.md를 만드는 데 집중합니다. (GitHub)
• 언제 쓰면 좋은지
  다중 서브시스템 프로젝트, 모호한 요구사항, 병렬 계획이 필요한 팀, 후속 planning 파이프라인의 입력을 정리해야 할 때 적합합니다. (GitHub)
• 언제 쓰면 안 되는지
  단일 기능, 작은 개선, 버그 수정처럼 이미 범위가 좁고 명확한 작업에는 과할 수 있습니다. (GitHub)
• 한 줄 요약
  deep-project는 “AI가 코드를 쓰기 전에, 무엇을 어떻게 나눠서 계획할지 먼저 정리하는 도구”라고 보면 가장 정확합니다. (GitHub)