Taskmaster AI 실무 가이드
"PRD 하나 던지면, AI가 알아서 할 일 목록을 만들어준다"
기준 버전: v0.43.0 (2026-03 기준 최신)
공식 레포: eyaltoledano/claude-task-master
Taskmaster AI
프로젝트를 시작하면 제일 먼저 하는 게 뭘까? "뭘 만들어야 하지?" 를 정리하는 거다.
보통은 기획 문서를 보고 직접 Task를 쪼개는데, Taskmaster AI는 이걸 AI가 대신 해준다.
기획 문서(PRD) → AI가 읽고 → Task 자동 생성 → 순서대로 작업Cursor, Windsurf, VS Code, Claude Code 같은 에디터에서 바로 연동해서 쓸 수 있다.
STEP 1. 설치 & 초기화
설치
npm install -g task-master-ai프로젝트 초기화
task-master init
# 특정 에디터 규칙만 적용하고 싶으면
task-master init --rules cursor,windsurf,vscode실행하면 인터랙티브하게 물어본다:
1. 프로젝트 이름
2. Main Model 선택 → 작업할 때 쓸 AI 모델
3. Research Model 선택 → 최신 정보 검색용 (선택사항이지만 권장)
4. Fallback Model 선택 → Main이 실패하면 자동으로 대신 쓸 모델
3개의 모델이 뭔지 헷갈리면 이렇게 기억하자:
- Main = 일하는 놈
- Research = 조사하는 놈
- Fallback = 백업
STEP 2. 폴더 구조 이해하기
init 하면 이런 폴더가 생긴다:
내 프로젝트/
├── .taskmaster/
│ ├── config.json ← 모델 설정 저장됨 (task-master models로 관리)
│ ├── state.json ← 태그 상태 추적 (수동 편집 금지)
│ ├── tasks/
│ │ └── tasks.json ← ★ 모든 Task가 여기에 저장됨
│ ├── docs/
│ │ └── prd.txt ← ★ 여기에 기획 문서 넣기 (.md도 가능)
│ └── templates/
│ └── example_prd.txt ← PRD 작성 예시
│
├── .cursor/
│ └── mcp.json ← Cursor에서 MCP 연동할 때 쓰는 설정
│
└── .env ← CLI로 쓸 때 API 키 넣는 곳기억할 것 두 가지:
- 기획 문서는
.taskmaster/docs/prd.txt(또는.md)에 넣는다 - Task 데이터는
.taskmaster/tasks/tasks.json에 자동 저장된다
STEP 3. MCP 연동 (Cursor 기준)
mcp.json 설정
.cursor/mcp.json에 이렇게 설정한다:
<{
"mcpServers": {
"task-master-ai": {
"command": "npx",
"args": ["-y", "task-master-ai"],
"env": {
"TASK_MASTER_TOOLS": "standard",
"ANTHROPIC_API_KEY": "sk-ant-여기에키",
"PERPLEXITY_API_KEY": "pplx-여기에키"
}
}
}
}
VS Code 사용 시:
"mcpServers"대신"servers"키를 사용한다.
TASK_MASTER_TOOLS옵션:"all","standard"(권장),"core"(토큰 절약),"lean", 또는 쉼표로 도구 직접 지정 가능.
Cursor에서 활성화
Cursor Settings (Ctrl+Shift+J) → MCP 탭 → task-master-ai 토글 켜기
토글 켰는데 0 tools라고 나오면? → 에디터 재시작 + API 키 확인
CLI vs MCP 차이가 뭐야?
- MCP: Cursor 채팅에서 자연어로 "Task 5 확장해줘" 이렇게 쓸 수 있음
- CLI: 터미널에서
task-master expand --id=5직접 입력공식 권장: 양쪽 다 API 키 넣어두기 (mcp.json + .env). mcp.json은
.gitignore에 추가해서 키가 Git에 올라가지 않게 할 것.
STEP 4. 실무 워크플로우
실제로 쓰는 순서는 이거다:
① PRD 작성
.taskmaster/docs/prd.txt (또는 .md)에 기획 문서를 작성한다. 상세할수록 Task 품질이 좋아진다.
처음이면
.taskmaster/templates/example_prd.txt보고 따라 쓰면 된다.
② Task 생성
task-master parse-prd .taskmaster/docs/prd.txtPRD를 AI가 읽고 Task를 자동 생성한다. 결과는 tasks.json에 저장됨.
# Task 수를 AI가 알아서 정하게 하려면
task-master parse-prd .taskmaster/docs/prd.txt --num-tasks=0
# 기존 Task에 추가하고 싶으면 (덮어쓰기 X)
task-master parse-prd .taskmaster/docs/prd.txt --append③ Task 확인
task-master list # 전체 목록
task-master list --with-subtasks # SubTask까지 보기④ 복잡도 분석 & SubTask 분해
# 어떤 Task가 복잡한지 분석
task-master analyze-complexity
task-master complexity-report # 결과를 읽기 쉽게 출력
# 복잡한 Task를 SubTask로 쪼개기
task-master expand --id=5 # Task 5만
task-master expand --all # 전부 다⑤ 작업 시작
# 다음에 뭐 해야 하는지 물어보기
task-master next
# 특정 Task 상세 보기
task-master show 3
task-master show 3.2 # SubTask 보기 (Task 3의 SubTask 2)⑥ 작업 완료 처리
task-master set-status --id=3 --status=doneTask를 done 처리하면 그 아래 SubTask도 전부 자동으로 done 된다.
⑦ 반복
task-master next # 다음 할 일 확인
# → 작업 → 완료 → next → 반복자주 쓰는 상황별 명령어
"방향이 바뀌었어" — 미완료 Task 일괄 수정
# Task 4번부터 이후 전부 수정
task-master update --from=4 --prompt="PostgreSQL 대신 MongoDB로 변경""Task 하나만 수정하고 싶어"
# 기존 내용을 대체
task-master update-task --id=3 --prompt="JWT 인증 방식으로 변경"
# SubTask에 내용 추가 (기존 유지 + 덧붙이기)
task-master update-subtask --id=5.2 --prompt="Rate limiting 100 req/min 추가"
update-task= 덮어쓰기,update-subtask= 이어쓰기. 이 차이 꼭 기억!
"Task를 직접 추가하고 싶어"
task-master add-task --prompt="사용자 인증 시스템 구현"
task-master add-task --prompt="OAuth 구현" --priority=high"의존성 관리"
task-master add-dependency --id=5 --depends-on=3 # Task 5는 Task 3 끝나야 시작
task-master remove-dependency --id=5 --depends-on=3 # 의존성 제거
task-master fix-dependencies # 꼬인 의존성 자동 수정"최신 기술 조사가 필요해"
task-master research "JWT 인증 Node.js 최신 모범 사례"
# 조사 결과를 Task에 바로 저장
task-master research "OAuth 2.0 구현 방법" --save-to=15"Git 머지했더니 Task ID가 충돌해"
# 내 Task 10,11,12를 16,17,18로 옮기기
task-master move --from=10,11,12 --to=16,17,18모델 설정 & 변경
# 현재 설정 확인
task-master models
# 인터랙티브 재설정
task-master models --setup
# 개별 모델 직접 변경
task-master models --set-main=claude-sonnet-4-20250514
task-master models --set-research=sonar-pro
task-master models --set-fallback=claude-3-haiku-20240307Task 상태 종류
| 상태 | 의미 | 언제 쓰나 |
|---|---|---|
pending | 대기 중 | 아직 시작 안 한 Task |
in-progress | 진행 중 | 지금 작업하고 있는 Task |
done | 완료 | 끝난 Task (SubTask도 자동 완료) |
review | 리뷰 대기 | 코드 리뷰 등 확인 필요 |
deferred | 보류 | 나중에 하기로 한 Task |
cancelled | 취소 | 안 하기로 한 Task |
task-master set-status --id=3 --status=in-progress
task-master set-status --id=1,2,3 --status=done # 여러 개 한번에
task-master set-status --id=3.1,3.2 --status=done # SubTask도 가능참고:
blocked라는 별도 상태값은 없다. 의존성이 충족되지 않은 Task는next명령에서 자동으로 제외되는 방식으로 처리된다.
팁: Task를 삭제하기보다
deferred나cancelled로 바꾸는 게 낫다. 나중에 참고할 수 있으니까.
API 비용 — 이거 돈 드는 거야?
맞다. AI를 호출하는 명령어를 쓸 때마다 해당 프로바이더의 API 비용이 발생한다.
비용 발생 O / X 구분
쉽게 구분하는 법: AI가 "생각"해야 하면 유료, 단순 조회·수정이면 무료
| 유료 (AI 호출) | 무료 (로컬 처리) |
|---|---|
parse-prd — PRD 분석 | list — 목록 조회 |
expand — SubTask 생성 | show — 상세 보기 |
update / update-task — 내용 수정 | next — 다음 Task 확인 |
add-task — 새 Task 생성 | set-status — 상태 변경 |
analyze-complexity — 복잡도 분석 | move — Task 이동 |
research — 정보 탐색 | generate — .md 파일 생성 |
add-dependency — 의존성 추가 | |
fix-dependencies — 의존성 수정 |
얼마나 들어?
| 작업 | 대략적 비용 |
|---|---|
parse-prd 1회 | ~$0.01 ~ $0.05 |
expand 1회 | ~$0.01 ~ $0.03 |
expand --all (Task 10개) | ~$0.10 ~ $0.30 |
analyze-complexity | ~$0.03 ~ $0.10 |
| 프로젝트 한 사이클 전체 | ~$0.20 ~ $0.50 |
솔직히 부담되는 금액은 아니다.
비용 아끼는 법
Claude Code 구독이 있다면 → 추가 비용 0원!
<task-master models --setup
# → claude-code 모델 선택하면 구독 안에 포함
구독이 없다면:
- Fallback 모델을 저렴한 걸로 설정:
--set-fallback=claude-3-haiku-20240307 --research플래그는 정말 필요할 때만 사용- MCP Tool 모드를
core로 설정하면 토큰 약 70% 절감
Cursor에서 자연어로 쓰기
MCP 연동이 되어 있으면 터미널 명령어 안 쳐도 된다. Cursor 채팅에서 이렇게 말하면 끝:
"다음에 작업할 Task가 뭐야?"
"Task 5를 SubTask로 쪼개줘"
"Task 3 완료했어. 상태 업데이트해줘"
"MongoDB 대신 PostgreSQL로 바꿨어. 앞으로의 Task 업데이트해줘"
"JWT 인증 최신 모범 사례 조사해줘"트러블슈팅
| 이런 증상이면 | 이렇게 해결 |
|---|---|
| MCP에서 AI 명령 실패 | .cursor/mcp.json에 해당 프로바이더 API 키 확인 |
| CLI에서 AI 명령 실패 | .env 파일에 해당 프로바이더 API 키 확인 |
| MCP에서 0 tools 표시 | 에디터 재시작 + API 키 재확인 |
| "Task가 없다"고 나옴 | parse-prd 먼저 실행했는지 확인 |
| 의존성 에러 | task-master fix-dependencies 실행 |
| tasks.json Git 충돌 | task-master move로 ID 재배치 |
| 재초기화해도 안 고쳐짐 | init은 해결책이 아님. 구체적 에러 먼저 확인 |
명령어 치트시트
# ===== 시작 =====
task-master init # 프로젝트 초기화
task-master parse-prd .taskmaster/docs/prd.txt # PRD → Task 생성
# ===== 확인 =====
task-master list --with-subtasks # 전체 목록 (SubTask 포함)
task-master next # 다음 할 일
task-master show <id> # Task 상세
task-master show 1,3,5 # 여러 Task 한번에
# ===== 분석 & 분해 =====
task-master analyze-complexity # 복잡도 분석
task-master complexity-report # 리포트 보기
task-master expand --id=<id> # SubTask로 분해
task-master expand --all # 전부 분해
# ===== 작업 =====
task-master set-status --id=<id> --status=done # 완료 처리
task-master update --from=<id> --prompt="변경" # 일괄 수정
task-master update-task --id=<id> --prompt="변경" # 단일 수정 (덮어쓰기)
task-master update-subtask --id=<id> --prompt="추가" # SubTask 수정 (이어쓰기)
task-master add-task --prompt="설명" # Task 추가
# ===== 의존성 =====
task-master add-dependency --id=<id> --depends-on=<id>
task-master fix-dependencies
# ===== 모델 =====
task-master models # 현재 설정 확인
task-master models --setup # 재설정
# ===== 리서치 =====
task-master research "질문" # 최신 정보 조사
task-master research "질문" --save-to=<id> # 결과를 Task에 저장