사용자 결과에 맞게 구현하기 | Build

Overview

완성된 spec.md에는 이번에 만들 사용자 결과와 완료 기준이 적혀 있습니다. 이제 하나의 사용자 흐름으로 구현할지, 독립적으로 완성할 결과를 Task로 나눌지 결정해야 합니다.

이번 Lesson에서는 사용자 결과에 맞는 구현 경로를 정하고, 구현 중 발견한 문제를 현재 작업에서 해결할지 별도 기록으로 남길지 판단합니다. 마지막에는 실행한 서비스의 실제 동작과 전체 검증을 완료하고, 자동 코드 리뷰의 근거와 남은 상태를 확인합니다.

학습 목표

• Spec이 하나의 사용자 흐름인지, 독립적으로 전달할 결과가 여러 개인지 판단해 구현 경로를 선택합니다.
• 구현 중 발견한 문제를 현재 구현, shaping, follow-up 기록과 근거 확인 경로로 구분합니다.
• 첫 테스트 전에 테스트할 동작과 확인 방법을 합의하고, 적용할 수 있는 동작을 Red → Green → Refactor 순서로 구현합니다.
• 실제 서비스 동작과 전체 검증으로 완료 기준을 확인하고, 자동 코드 리뷰의 근거와 남은 상태를 보고합니다.

spec.md에서 구현할 결과 확인하기

먼저 Lesson 2에서 만든 docs/specs/<slug>/spec.md를 엽니다. 구현 방법을 새로 정하기보다 다음 내용을 확인합니다.

• 사용자가 최종적으로 할 수 있어야 하는 동작
• 각 동작이 완료됐다고 판단할 기준
• 구현 중 지켜야 할 가정과 제외 범위
• 아직 사람의 결정이 필요한 위험

하나의 흐름으로 구현할지 Task로 나눌지 정하기

분할 기준은 시간, 파일 수나 코드 양이 아니라 하나씩 완성할 때마다 사용자가 바로 쓸 수 있는 결과가 여러 개인지입니다. 이런 결과가 여러 개이거나 결과 사이의 의존 순서를 추적해야 할 때만 Task로 나눕니다.

두 경로의 완료 기준은 같습니다. 달라지는 것은 진행 상태를 Spec 하나로 관리할지, 여러 Task로 나눠 관리할지입니다.

Feedme는 여기에 해당합니다. 주소를 넣어 본문을 Markdown으로 읽는 것까지만 만들어도 사용자는 바로 쓸 수 있습니다. 결과를 복사하거나 내려받는 일, 외부 LLM으로 보내는 일은 그 뒤에 하나씩 붙여도 됩니다. 그래서 Task로 나눠 구현합니다.

implement: 하나의 사용자 흐름 구현하기

implement는 선택한 Spec 폴더와 현재 코드를 읽고, 완료 기준을 충족할 때까지 구현과 검증을 이어갑니다.

/implement @docs/specs/<slug>/

첫 테스트를 만들기 전에 implement가 어떤 사용자 동작을 어디에서 확인할지 제안하면 사람과 먼저 합의합니다. 자동으로 확인할 수 있는 동작은 실패하는 테스트를 확인한 뒤 이를 통과하는 최소 구현을 만들고, 동작을 유지한 채 코드를 정리합니다. 자동 테스트가 어려운 화면은 브라우저에서 확인합니다. 테스트와 빌드가 통과해도 바뀐 동작을 실행한 서비스에서 확인하지 못했다면 완료가 아닙니다.

코드를 바꾸기 전에 방법을 먼저 보고 싶다면 Plan Mode에서 같은 명령을 실행합니다. 구현 중 사용자 동작, 범위나 완료 기준을 바꿔야 한다면 임의로 코드에 반영하지 않고 shape-idea로 돌아가 spec.md를 다시 정합니다.

split-into-tasks: 독립된 사용자 결과 나누기

split-into-tasks는 바로 Task 파일을 만들지 않습니다. 어떻게 나눌지 먼저 제안하고, 사람이 승인한 뒤에만 docs/specs/<slug>/tasks/에 문서를 만듭니다.

/split-into-tasks @docs/specs/<slug>/

Task는 화면, API, 테스트 같은 개발 단계가 아니라 하나를 끝낼 때마다 쓸 수 있는 결과 단위로 묶습니다.

사람의 중간 확인은 보안, 데이터 변경, 권한처럼 자동 검증만으로 판단하기 어려운 위험이 있을 때만 추가합니다. 승인이 끝나면 앞과 같은 /implement 명령을 다시 실행합니다. 이번에는 tasks/의 문서를 의존 순서대로 구현하고, 모든 Task가 끝나면 전체 결과를 다시 검증합니다.

구현 중 발견한 문제의 경로 정하기

구현 중 예상 밖의 문제가 드러나면 문제 자체보다 이번 결과와 어떤 관계인지 먼저 봅니다. follow-up은 이번 결과를 막지는 않지만 나중에 다시 확인해야 하는 별도 문제입니다.

다이어그램의 네 경로는 다음처럼 고릅니다.

• 정해진 동작으로 현재 완료 기준을 충족하지 못하면 지금 고칩니다.
• 사용자 동작, 범위나 완료 기준을 바꿔야 하면 shape-idea로 돌아갑니다.
• 이번 결과와 별개이고 확인한 근거가 있는 문제만 follow-up으로 남깁니다.
• 추측만 있다면 기록하지 않고 근거부터 확인합니다.

spec.md와 Task는 이번 결과를 완성하는 데 쓰고, docs/follow-ups/는 이번 결과 밖의 열린 문제에만 씁니다. 다음 작업에서도 따라야 할 확정된 규칙은 docs/decisions/에 둡니다.

기록 형식은 project-knowledge가 맡습니다. 사람은 이 문제가 근거가 있는 별도 문제인지만 판단합니다.

이 기록을 실제로 해결하는 조건과 경로는 배포 뒤 프로젝트 이어가기에서 다룹니다.

전체 검증과 자동 코드 리뷰 근거 남기기

기능 하나의 테스트가 통과했다고 구현이 끝난 것은 아닙니다. implement는 모든 결과를 만든 뒤 다음 검증과 리뷰 근거를 남깁니다.

1. 관련 테스트와 전체 테스트, 정적 검사와 빌드를 실행합니다.
2. 실행한 서비스에서 실제 사용자 동작으로 spec.md의 완료 기준을 확인합니다.
3. 현재 실행 환경의 자동 코드 리뷰로 전체 구현 차이를 한 번만 Spec과 완료 기준에 대조하고 finding을 분류합니다.

반드시 고칠 finding은 수정하고 영향받은 검증을 다시 실행합니다. 같은 범위의 전체 변경을 코드 리뷰에 다시 보내지는 않습니다. 리뷰를 사용할 수 없거나 오류·타임아웃·거부 상태이면 그 상태와 다시 실행할 명령을 보고합니다. 완료 기준과 실제 검증을 통과했다면 리뷰 도구의 상태만으로 구현을 미완료로 되돌리지는 않습니다.

[미션] Feedme 구현 완료하기

Lesson 2에서 spec.md를 만든 feedme-clone 저장소를 그대로 사용합니다.

Step 1: Task 제안받고 승인하기

먼저 spec.md에서 하나씩 완성해 사용할 수 있는 결과를 찾아, Feedme가 Task 경로에 맞는 이유를 설명합니다.

다음 명령을 실행합니다. <slug>에는 Lesson 2에서 생성된 실제 폴더 이름을 넣습니다.

/split-into-tasks @docs/specs/<slug>/

제안된 Task를 그대로 승인하지 말고, 하나가 끝날 때마다 사용자가 쓸 수 있는 결과가 남는지 확인합니다. 각자의 spec.md에 따라 Task 개수는 달라질 수 있습니다.

승인하면 docs/specs/<slug>/tasks/에 Task 문서가 생깁니다.

Step 2: 구현 시작하기

같은 명령으로 승인된 Task를 순서대로 구현합니다.

/implement @docs/specs/<slug>/

코드가 바뀌기 전에 implement가 제안한 테스트 동작과 확인 방법을 읽고 승인합니다. 제안 없이 구현을 시작하려 한다면 먼저 무엇을 어디에서 확인할지 물어봅니다.

Step 3: 완료 결과 확인하기

Task 문서마다 완료 상태와 검증 근거가 남았는지 보고, 자동 테스트를 적용한 동작은 실패하는 테스트 확인 → 최소 구현 → 코드 정리 순서로 진행했는지 구현 대화와 변경 기록에서 확인합니다. 이어서 브라우저에서 spec.md의 완료 기준이 실제로 동작하는지 봅니다. 프로젝트의 테스트와 검사 명령이 통과하고, 자동 코드 리뷰를 한 번 실행한 근거와 finding 처리 결과가 남아 있어야 합니다. 리뷰를 사용할 수 없었다면 그 상태와 다시 실행할 명령이 기록됐는지 확인합니다.

docs/follow-ups/에 파일이 생겼다면 확인한 근거가 있는지, 지금 해결하지 않아도 현재 spec.md를 완료할 수 있는지 설명합니다. 둘 중 하나라도 아니라면 follow-up 경로가 아닙니다. 조건에 맞는 문제가 없다면 연습용 파일을 만들지 않습니다.

핵심 포인트 정리

1. 사용자 결과로 경로 선택: 하나의 사용자 흐름이면 implement로 바로 실행하고, 하나씩 완성해 쓸 수 있는 결과가 여러 개이거나 결과 사이의 의존 순서를 추적해야 할 때만 split-into-tasks를 사용합니다.
2. 동작하는 결과로 분할: Task는 개발 단계가 아니라 하나를 끝낼 때마다 쓸 수 있는 결과 단위로 나눕니다.
3. 실제 동작까지 확인: 테스트와 빌드는 실행한 서비스에서 바뀐 동작을 확인하는 과정을 대신하지 않습니다.
4. 별도 문제만 follow-up으로 보존: 현재 완료 기준을 막는 문제는 지금 고치고, 제품 계약을 바꿔야 하면 shaping으로 돌아가며, 이번 결과와 별개인 근거 있는 문제만 docs/follow-ups/에 남깁니다.

이어서 배울 내용

구현과 자동 검증이 끝나도 사람이 직접 보고 판단해야 할 결과가 남을 수 있습니다. 다음 Lesson에서는 human-review로 실제 결과를 확인하고 필요한 수정 내용을 전달합니다.