Claude Code로 투두리스트 만들기: 기획부터 구현, 테스트, 문서화까지

AI 코딩 도구를 활용할 때 처음부터 모든 기능을 한 번에 구현하도록 요청하면 요구사항이 누락되거나 기존 프로젝트 구조와 맞지 않는 코드가 만들어질 수 있습니다.

이번 글에서는 투두리스트(To-do List)를 예제로 Claude Code를 활용한 개발 과정을 정리합니다. 요구사항 분석부터 설계, 구현, 테스트, 문서화, 최종 점검까지 여섯 단계로 나누어 진행합니다.

작성 기준일: 2026년 11월 3일

핵심 내용

Sonnet을 주 작업 모델로 사용하고, 복잡한 설계나 반복 오류 검토에는 Opus Advisor를 활용합니다. 기존 코드 탐색은 Haiku 기반 Subagent에 맡기고, 단계별 결과는 Markdown 파일로 저장해 다음 작업에 전달하는 방식입니다.

1. 전체 개발 프로세스

전체 과정은 다음과 같습니다.

기획: 요구사항 수집 및 확정
설계: 화면, API, 데이터베이스, Command/Query 설계
구현: DB, Handler, Controller, Vue 순서로 개발
테스트: 테스트 시나리오 작성 및 실행
문서화: 실제 구현 내용을 개발 문서로 정리
종료: 보안 점검, 사용량 확인, Git 커밋

각 단계가 끝나면 결과물을 파일로 저장하고, 다음 단계에서는 해당 파일을 읽어 작업합니다. 작업 성격에 따라 /clear로 새로운 세션을 시작하면 이전 대화의 불필요한 문맥이 누적되는 것을 줄일 수 있습니다.

2. 사전 준비

2-1. 프로젝트 폴더 구성

프로젝트 루트에 다음 구조를 준비합니다.

ProjectRoot/
├── CLAUDE.md
├── .claude/
│   └── agents/
│       └── explorer.md
└── docs/
    ├── 01-requirements.md
    ├── 02-design.md
    ├── 04-test.md
    └── 05-dev-doc.md

CLAUDE.md: 프로젝트 기술 스택과 개발 규칙
explorer.md: 기존 코드 탐색을 위한 Subagent 설정
docs/: 단계별 산출물 저장 공간

2-2. CLAUDE.md 작성

프로젝트에서 사용하는 기술과 반드시 지켜야 할 규칙을 작성합니다.

# Project Development Rules

## Technology Stack
- ASP.NET Core 8 MVC
- C#
- Dapper
- MediatR.SourceGenerator
- SQL Server
- Vue 3 CDN Options API
- jQuery

## Architecture
- Follow the existing project architecture.
- Separate Application, Domain, Infrastructure and WebUI.
- Use CQRS for commands and queries.
- Follow existing Controller and Handler patterns.

## Development Rules
- Inspect existing code before creating new files.
- Do not introduce unnecessary dependencies.
- Do not modify unrelated files.
- Validate user permissions on the server.
- Handle exceptions explicitly.
- Never execute DROP, TRUNCATE or DELETE
  operations without explicit approval.

## Testing
- Build the project after implementation.
- Verify database changes.
- Test success and failure scenarios.
- Report untested items honestly.

CLAUDE.md에는 프로젝트 전체에 적용할 규칙을 작성합니다. 특정 기능의 상세한 구현 절차까지 모두 넣기보다는 반복 작업은 Subagent나 Skill로 분리하는 편이 관리하기 쉽습니다.

2-3. explorer Subagent 작성

기존 프로젝트의 파일 위치, Command Handler, Query Handler, SQL 파일 등을 조사하는 탐색 전용 에이전트입니다.

.claude/agents/explorer.md

---
name: explorer
description: >
  기존 프로젝트의 파일 위치, 클래스 구조,
  Command Handler, Query Handler 및 SQL 파일을
  조사할 때 사용합니다.
model: haiku
tools:
  - Read
  - Grep
  - Glob
---

You are a read-only codebase exploration agent.

Your responsibilities:
1. Inspect the existing project structure.
2. Find related classes and SQL files.
3. Identify existing coding patterns.
4. Report file paths and relevant code locations.
5. Never modify or create files.
6. Return a concise summary to the main agent.

Always follow the project's CLAUDE.md rules.

이 에이전트는 읽기 중심의 조사 작업을 수행하도록 구성했습니다. 별도 모델 요청이 발생하므로 Subagent를 사용한다고 사용량이 없어지는 것은 아닙니다.

3. Claude Code 실행

프로젝트 루트에서 터미널을 실행합니다.

claude --model sonnet --advisor opus

--model sonnet: 주 작업 모델을 Sonnet으로 지정합니다.
--advisor opus: 보조 검토 모델로 Opus를 지정합니다.

Advisor는 모든 요청에 Opus를 사용하는 방식이 아닙니다. 복잡한 판단이 필요한 작업에서 보조 검토를 요청하는 구조입니다.

주의사항

Advisor는 실험적 기능입니다. 지원 모델, 인증 방식, 계정 조건 및 실행 환경에 따라 사용 가능 여부가 달라질 수 있습니다. 위 명령은 실제 설치 버전에서 지원 여부를 확인한 후 사용해야 합니다.

4. 1단계: 기획 및 요구사항 정리

먼저 투두리스트에 필요한 기능을 정의합니다. 데이터베이스나 Controller부터 만들지 말고 사용자 요구사항을 먼저 확정합니다.

입력 프롬프트

투두리스트 기능을 개발하려고 해.

먼저 요구사항을 질문 형태로 정리해줘.

다음 항목을 중심으로 확인해줘.

1. 할 일 등록
2. 할 일 목록 조회
3. 완료 및 미완료 상태 변경
4. 할 일 삭제
5. 로그인 사용자별 데이터 관리 여부
6. 필수 입력값과 유효성 검사
7. 예외 상황과 권한 처리

중요한 항목부터 순서대로 질문해줘.

내 답변을 반영해 요구사항을 확정하고
docs/01-requirements.md 파일로 저장해줘.

저장 후 누락된 요구사항이 없는지 검토해줘.

질문에 답하면서 실제 서비스 정책을 결정합니다. 예를 들어 사용자별 목록을 관리한다면 다른 사용자의 데이터를 조회하거나 수정하지 못하도록 서버에서 권한을 검증해야 합니다.

확인 사항

등록, 조회, 완료, 삭제 기능이 모두 정의되었는가?
사용자별 데이터 분리 정책이 명확한가?
필수 입력값과 오류 상황이 정의되었는가?
요구사항 파일이 실제로 저장되었는가?

검토가 끝나면 다음 명령으로 새 세션을 시작합니다.

/clear

5. 2단계: 시스템 설계

확정된 요구사항을 바탕으로 화면, API, 데이터베이스, Command/Query 구조를 설계합니다.

입력 프롬프트

docs/01-requirements.md 파일을 읽고
투두리스트 기능의 기술 설계를 진행해줘.

다음 항목을 정리해줘.

1. 화면 구성과 사용자 동작
2. API 엔드포인트 및 요청·응답 구조
3. 데이터베이스 테이블과 컬럼
4. Command 및 Query 목록
5. Handler의 책임
6. Controller 구성
7. Vue 3 화면과 API 연동 방식
8. 입력값 및 권한 검증
9. 예외 처리와 테스트 고려사항

기존 프로젝트의 CLAUDE.md 규칙을 준수해줘.

필요하면 explorer Subagent로
기존 프로젝트 구조를 조사해줘.

설계 결과를 docs/02-design.md에 저장해줘.

저장하기 전에 Opus Advisor로
설계 누락과 구조적인 문제를 검토해줘.

검토 의견과 반영 여부도 기록해줘.

설계가 완료되면 API와 요구사항의 일치 여부, 테이블 관계, Handler의 책임, 기존 프로젝트 구조와의 호환성을 확인합니다.

검토가 끝나면 /clear를 실행합니다.

6. 3단계: 실제 기능 구현

구현은 한 번에 진행하지 않습니다. 데이터베이스부터 화면까지 작은 단위로 나누어 작업합니다.

6-1. 기존 프로젝트 분석

docs/01-requirements.md와
docs/02-design.md를 읽어줘.

먼저 explorer Subagent를 사용해
기존 프로젝트 구조를 조사해줘.

다음 항목을 찾아줘.

1. Command Handler 위치
2. Query Handler 위치
3. SQL 파일 위치 및 작성 패턴
4. Controller 작성 방식
5. Vue 화면 구성 방식
6. 공통 응답 및 예외 처리 방식

코드는 수정하지 말고
관련 파일 경로와 기존 패턴을 정리해줘.

6-2. 데이터베이스 구현

docs/02-design.md를 기준으로
투두리스트 데이터베이스를 설계해줘.

기존 SQL 작성 규칙을 따라줘.

1. 테이블 생성 스크립트
2. 기본키 및 외래키
3. 사용자 식별 컬럼
4. 필수 컬럼과 기본값
5. 조회에 필요한 인덱스

SQL 파일은 기존 프로젝트 규칙에 맞춰 저장해줘.

실제 데이터베이스 변경은 수행하지 말고
먼저 SQL 스크립트와 검토 결과를 보여줘.

실제 DB 변경은 SQL을 검토한 후 별도로 승인하고 진행합니다. 운영 데이터가 존재하는 환경에서는 삭제나 초기화 작업을 자동으로 수행하지 않도록 합니다.

6-3. Command 및 Query 구현

docs/02-design.md와 기존 Handler 패턴을
기준으로 구현해줘.

다음 기능을 분리해서 작성해줘.

1. CreateTodoCommand
2. CompleteTodoCommand
3. DeleteTodoCommand
4. GetTodoListQuery

기존 프로젝트의 Dapper 및
MediatR.SourceGenerator 사용 방식을 따라줘.

사용자 권한과 입력값 검증을 포함하고
기존 코드와 중복되는 기능이 있는지 확인해줘.

파일을 생성한 뒤 변경 내용을 설명해줘.

6-4. Controller 구현

설계서에 정의된 API를 기준으로
TodoController를 구현해줘.

다음 항목을 확인해줘.

1. API 라우팅
2. 요청 모델 검증
3. Command 및 Query 호출
4. 인증 사용자 식별
5. 권한 검증
6. 성공 및 실패 응답
7. 예외 처리

기존 BaseController와 공통 응답 구조를
우선적으로 활용해줘.

6-5. Vue 3 화면 구현

투두리스트 화면을 Vue 3 CDN
Options API 방식으로 구현해줘.

다음 기능을 포함해줘.

1. 할 일 목록 조회
2. 할 일 등록
3. 완료 상태 변경
4. 할 일 삭제
5. API 요청 중 로딩 상태 표시
6. API 오류 메시지 표시

기존 프로젝트의 화면 구성과 스타일을
최대한 유지해줘.

실제 API 응답 구조에 맞춰 연동하고
불필요한 라이브러리는 추가하지 말아줘.

각 구현 단계가 끝날 때마다 변경된 파일을 확인하고 빌드 및 실행 결과를 검증합니다. 구현이 완료되면 /clear로 새 세션을 시작합니다.

7. 4단계: 테스트 및 오류 수정

코드가 생성되었다고 기능 개발이 끝난 것은 아닙니다. 요구사항에 정의한 기능이 실제로 동작하는지 확인해야 합니다.

입력 프롬프트

docs/01-requirements.md와
docs/02-design.md를 기준으로
투두리스트 테스트를 진행해줘.

먼저 docs/04-test.md에
테스트 시나리오를 작성해줘.

다음 항목을 포함해줘.

1. 할 일 정상 등록
2. 필수값 누락
3. 목록 정상 조회
4. 완료 상태 변경
5. 다른 사용자의 데이터 접근 차단
6. 할 일 삭제
7. 존재하지 않는 데이터 요청
8. API 예외 상황

테스트 환경과 실행 방법을 명시하고
실제로 실행 가능한 테스트는 진행해줘.

실행하지 못한 항목은 미실행으로 표시하고
실패한 항목은 원인과 수정 내용을 기록해줘.

같은 유형의 오류가 반복되면
Opus Advisor를 활용해 원인을 검토해줘.

테스트 결과는 실제 실행 여부에 따라 구분합니다.

PASS: 실제 테스트를 실행해 통과
FAIL: 실행 결과 오류 발생
NOT RUN: 실행하지 못한 항목
BLOCKED: 선행 조건이나 외부 환경 문제로 진행 불가

실패한 항목은 원인을 분석하고 수정한 다음 다시 테스트합니다. 실행하지 않은 항목을 PASS로 표시해서는 안 됩니다.

8. 5단계: 개발 문서 작성

테스트까지 마쳤다면 앞에서 작성한 문서를 하나로 정리합니다.

다음 문서를 모두 읽어줘.

- docs/01-requirements.md
- docs/02-design.md
- docs/04-test.md

실제 구현된 코드와 비교해서
투두리스트 개발 문서를 작성해줘.

다음 항목을 포함해줘.

1. 개발 목적과 요구사항
2. 전체 시스템 구조
3. 데이터베이스 구조
4. API 목록
5. Command 및 Query 구성
6. 화면 구성과 동작 방식
7. 테스트 결과
8. 알려진 제한사항
9. 향후 개선 사항

설계서와 실제 구현이 다른 부분은
차이점을 명확하게 기록해줘.

최종 결과를 docs/05-dev-doc.md에 저장해줘.

설계 문서에 작성된 내용과 실제 구현이 다를 수 있으므로, 구현되지 않은 기능을 완료된 것처럼 문서화하지 않도록 확인합니다.

9. 6단계: 최종 점검 및 종료

마지막으로 보안, 권한, 예외 처리 및 변경 사항을 검토합니다.

투두리스트 기능의 최종 점검을 진행해줘.

요구사항, 설계서, 테스트 결과와
실제 변경된 코드를 비교해줘.

다음 항목을 중점적으로 확인해줘.

1. 인증 및 사용자 권한 검증
2. 다른 사용자의 데이터 접근 가능성
3. 입력값 검증
4. SQL 파라미터 처리
5. 예외 처리와 오류 응답
6. 불필요한 코드 및 중복 로직
7. 성능상 문제가 될 수 있는 조회 방식
8. 테스트 누락 항목
9. 설계와 실제 구현의 차이

중요한 설계 및 보안 판단은
Opus Advisor의 검토를 요청해줘.

코드를 변경하기 전에는 수정 대상과
예상되는 영향을 먼저 설명해줘.

최종 결과를 점검 보고서로 정리해줘.

점검이 끝나면 다음 명령으로 사용량을 확인합니다.

/usage

세션의 토큰 사용량과 모델별 사용 내역 등을 확인할 수 있습니다. 실제 비용은 계정 유형과 과금 방식에 따라 다르므로 구독 사용량과 API 사용량을 구분해야 합니다.

마지막으로 Git 변경 사항을 확인하고 커밋합니다. 커밋 전에는 테스트 결과와 변경 파일을 직접 검토하는 것이 좋습니다.

10. 주니어 개발자가 기억할 다섯 가지

① 모델 변경을 무조건 금지할 필요는 없다

Sonnet을 주 모델로 유지하면 작업의 일관성을 관리하기 쉽습니다. 다만 /model로 모델을 변경한다고 해서 항상 캐시가 깨지거나 비용이 증가하는 것은 아닙니다. 캐시 동작은 모델과 요청 조건에 따라 달라집니다.

② 단계별 결과는 파일로 저장한다

기획과 설계 내용을 파일로 남기면 새로운 세션에서도 이전 결정 사항을 확인할 수 있습니다. /clear는 대화를 초기화하는 명령이며 프로젝트 파일을 삭제하는 명령이 아닙니다.

③ Opus Advisor는 중요한 판단에 활용한다

설계 검토, 반복 오류 분석, 보안 점검처럼 판단의 중요도가 높은 작업에 활용합니다. 보조 모델 호출도 사용량에 영향을 줄 수 있습니다.

④ Subagent도 사용량을 고려한다

Haiku 기반 탐색 에이전트는 코드 검색이나 구조 분석처럼 읽기 중심의 작업에 적합합니다. 다만 별도 모델 요청이므로 사용량이 발생할 수 있습니다.

⑤ AI가 작성한 코드는 직접 실행한다

코드 생성과 정상 동작은 다른 문제입니다. 빌드, 테스트, 실제 화면 확인을 거쳐야 기능이 완성되었다고 판단할 수 있습니다.

11. 자주 묻는 질문

Q1. 매 단계마다 반드시 /clear를 실행해야 하나요?

반드시 그럴 필요는 없습니다. 독립적인 작업으로 넘어갈 때 사용하면 좋습니다. 이전 설계나 구현 내용을 계속 참조해야 한다면 같은 세션을 유지해도 됩니다.

Q2. explorer Subagent를 반드시 만들어야 하나요?

아닙니다. Claude Code에는 기본 Explore 에이전트도 있습니다. 반복적으로 사용할 탐색 규칙이나 모델을 별도로 지정하고 싶을 때 사용자 정의 Subagent를 만들면 됩니다.

Q3. Opus Advisor는 모든 프롬프트를 검토하나요?

모든 요청을 자동으로 검토하는 방식은 아닙니다. 판단이 필요한 시점에 활용하는 보조 기능입니다. 특정 단계의 검토가 필요하다면 프롬프트에 명시하는 것이 좋습니다.

Q4. /usage에 표시된 금액이 실제 결제 금액인가요?

항상 그렇지는 않습니다. API 사용 환경의 비용 정보와 구독 계정의 사용량 정보는 다를 수 있으므로 공식 과금 내역을 함께 확인해야 합니다.

Q5. 처음부터 복잡한 기능을 개발해도 될까요?

처음에는 투두리스트처럼 작은 기능으로 전체 개발 흐름을 익히는 것을 권장합니다. 이후 게시판, 파일 업로드, 결재 기능처럼 복잡한 업무 기능으로 확장하면 됩니다.

마무리

Claude Code를 활용한 개발에서 중요한 것은 AI에게 한 번에 얼마나 많은 코드를 작성하도록 요청하느냐가 아닙니다.

요구사항을 정확하게 정의하고, 설계 결과를 검토하고, 작은 단위로 구현한 다음 실제 실행 결과를 확인하는 과정이 중요합니다.

이번 투두리스트 예제로 전체 개발 흐름을 한 번 경험해 보세요. 익숙해지면 기존 ASP.NET Core 프로젝트에서도 AI를 코드 생성뿐 아니라 설계, 구현, 테스트를 함께 수행하는 개발 보조 도구로 활용할 수 있습니다.

참고 자료

작성 및 업데이트 안내

2026년 11월 3일 기준으로 작성한 개발 워크플로 예시입니다. CLI 옵션과 Advisor 기능의 지원 여부는 설치 버전 및 계정 환경에 따라 달라질 수 있습니다. 제시한 코드는 구성 예시이며 실제 프로젝트에서 실행 및 검증한 결과가 아닙니다. 적용 전 공식 문서와 현재 설치 버전을 확인하시기 바랍니다.

#ClaudeCode #ClaudeCode사용법 #OpusAdvisor #Sonnet #Haiku #Subagent #ASPNetCore #CSharp #CQRS #AI개발 #개발자동화 #프롬프트엔지니어링

LUCKY BLOG

Pinned Post