2025년 12월 14일·5분
Claude Code 작업 범위 정의: 모호한 요청에서 커밋까지
모호한 기능 요청을 명확한 수용 기준, 최소 UI/API 계획, 그리고 작은 커밋들로 바꾸는 Claude Code 작업 범위 설정 방법을 배우세요.
모호한 기능 요청을 명확한 수용 기준, 최소 UI/API 계획, 그리고 작은 커밋들로 바꾸는 Claude Code 작업 범위 설정 방법을 배우세요.
“더 나은 검색 추가”, “온보딩을 부드럽게 만들기”, “사용자에게 알림 필요”처럼 모호한 요청은 무해해 보입니다. 실제 팀에서는 한 줄짜리 채팅 메시지, 화살표가 그려진 스크린샷, 또는 반쯤 기억나는 고객 통화로 도착하는 경우가 많습니다. 모두 동의하지만 각자 상상하는 바는 다릅니다.
비용은 나중에 드러납니다. 범위가 불분명하면 사람들은 추측에 기반해 개발합니다. 첫 데모가 또 다른 정리 라운드로 변합니다: “제가 말한 게 이게 아니었어요.” 작업이 다시 이루어지고 변경이 은근히 커집니다. 디자인 수정은 코드 변경을 유발하고, 그러면 더 많은 테스트가 필요해집니다. 모호한 변경은 검증하기 어렵기 때문에 리뷰가 느려집니다. 만약 아무도 “정답”이 무엇인지 정의할 수 없으면 리뷰어들은 품질을 확인하는 대신 동작에 대해 논쟁하게 됩니다.
모호한 작업은 보통 초기에 눈에 띕니다:
잘 스코핑된 작업은 팀에 종료선을 제공합니다: 명확한 수용 기준, 최소 UI 및 API 계획, 포함되지 않는 항목에 대한 명시적 경계. 이 차이가 “검색 개선”과 쉽게 만들고 리뷰할 수 있는 작은 변경 사이를 나눕니다.
실용적인 습관 하나: “완료 정의(Definition of done)”와 “있으면 좋은 항목(nice-to-have)”을 분리하세요. “완료”는 실행할 수 있는 짧은 체크리스트입니다(예: “검색은 제목으로 결과를 반환하고, 빈 경우 ‘결과 없음’을 표시하며 쿼리를 URL에 유지한다”). “있으면 좋은 항목”은 나중으로 미룰 수 있는 모든 것들(동의어, 랭킹 조정, 하이라이트, 분석 등)입니다. 미리 표시하면 의도치 않은 범위 확장을 막을 수 있습니다.
모호한 요청은 종종 제안된 해결책으로 시작합니다: “버튼 추가”, “새 흐름으로 전환”, “다른 모델 사용”. 잠시 멈추고 제안을 먼저 결과로 번역하세요.
간단한 형식이 도움이 됩니다: “As a [user], I want to [do something], so I can [reach a goal].” 간단하게 유지하세요. 한 번에 말로 표현할 수 없다면 아직 모호합니다.
다음으로, 완료되었을 때 사용자에게 무엇이 바뀌는지 설명하세요. 구현 세부사항보다 보이는 동작에 집중하세요. 예: “폼 제출 후 확인 메시지를 보고 목록에서 새 레코드를 찾을 수 있다.” 이는 명확한 종료선을 만들고 ‘한 가지 더’가 슬며시 끼어드는 것을 어렵게 만듭니다.
또 무엇이 그대로 남는지도 적어 두세요. 비목표(Non-goals)는 범위를 보호합니다. 예를 들어 요청이 “온보딩 개선”이라면 비목표는 “대시보드 재설계 없음” 또는 “가격 책정 로직 변경 없음”일 수 있습니다.
마지막으로 먼저 지원할 기본 경로 하나를 선택하세요: 기능이 작동함을 증명하는 단일 엔드투엔드 슬라이스입니다.
예: “모든 곳에 스냅샷 추가” 대신 “프로젝트 소유자는 앱의 최신 스냅샷을 복원할 수 있어 실수로 인한 변경을 되돌릴 수 있다”라고 쓰세요. 비목표: “대량 복원 없음, UI 재설계 없음.”
모호한 요청은 노력 부족이 아니라 결정의 부재입니다.
범위를 조용히 바꾸는 제약부터 시작하세요. 기한도 중요하지만 접근 규칙과 준수 요구사항도 중요합니다. 티어와 역할이 있는 플랫폼에서 빌드한다면 누가 기능을 사용하는지, 어떤 요금제에서 가능한지 일찍 결정하세요.
그다음 하나의 구체적 예시를 요청하세요. 스크린샷, 경쟁사 동작, 이전 티켓은 “더 나은”이 실제로 무엇을 의미하는지 드러냅니다. 요청자가 예시가 없다면 마지막으로 문제가 느껴졌던 상황을 재현해 달라: 어떤 화면에 있었고 무엇을 클릭했고 무엇을 기대했는가?
엣지 케이스는 범위를 폭발시키는 곳이므로 큰 것들을 일찍 명명하세요: 빈 데이터, 검증 오류, 느리거나 실패한 네트워크 호출, 그리고 “되돌리기”가 실제로 무엇을 의미하는지.
마지막으로 성공을 어떻게 검증할지 결정하세요. 테스트 가능한 결과가 없으면 작업은 의견 싸움이 됩니다.
다음 다섯 질문은 대개 대부분의 모호함을 제거합니다:
예: “고객을 위한 커스텀 도메인 추가”는 어느 요금제에 속하는지, 누가 설정할 수 있는지, 호스팅 위치가 준수에 영향을 주는지, 잘못된 DNS에 대해 어떤 오류를 보여줄지, 그리고 “완료”가 무엇인지(도메인 검증, HTTPS 활성화, 안전한 롤백 계획) 결정하면 더 명확해집니다.
지저분한 요청은 목표, 추측, 반쯤 기억한 엣지 케이스를 섞어놓습니다. 당신의 일은 그것을 아무도 당신의 마음을 읽지 않고도 테스트할 수 있는 문장으로 바꾸는 것입니다. 동일한 기준이 디자인, 코딩, 리뷰, QA를 안내해야 합니다.
간단한 패턴이 명확함을 유지합니다. Given/When/Then을 쓰거나 동일한 의미의 짧은 불릿을 사용하세요.
각 기준을 한 사람이 실행할 수 있는 하나의 테스트로 작성하세요:
이제 적용해봅시다. 메모가 “스냅샷을 더 쉽게 만들자. 마지막 변경이 문제를 일으키면 롤백하고 싶다.”라면 테스트 가능한 문장으로 바꿉니다:
QA가 이 체크들을 실행할 수 있고 리뷰어가 UI와 로그에서 확인할 수 있다면 UI와 API 작업을 계획하고 작은 커밋으로 나눌 준비가 된 것입니다.
최소 UI 계획은 약속입니다: 기능이 작동함을 증명하는 가장 작은 가시적 변경입니다.
먼저 어떤 화면이 변경되는지와 사람이 10초 안에 무엇을 눈치챌지 이름을 지으세요. 요청이 “더 쉽게” 또는 “정리”를 요구하면 그것을 가리킬 수 있는 한 가지 구체적 변경으로 번역하세요.
디자인이 아니라 작은 지도처럼 쓰세요. 예: “Orders 페이지: 테이블 위에 필터 바 추가” 또는 “설정: 알림 아래에 새 토글 추가”. 화면과 정확한 요소를 이름으로 지을 수 없다면 범위는 아직 불명확합니다.
대부분의 UI 변경에는 몇 가지 예측 가능한 상태가 필요합니다. 해당되는 항목만 적으세요:
UI 카피도 범위의 일부입니다. 버튼 텍스트, 필드 레이블, 설명 텍스트, 오류 메시지처럼 승인되어야 할 문구를 캡처하세요. 문구가 아직 정해지지 않았다면 자리표시자 카피로 표시하고 누가 확인할지 적으세요.
필수는 아닌 항목(반응형 다듬기, 고급 정렬, 애니메이션, 새 아이콘)은 작은 “지금은 아니요” 노트로 남겨두세요.
스코프된 작업은 UI, 백엔드, 데이터 간의 작고 명확한 계약이 필요합니다. 목표는 전체 시스템을 설계하는 것이 아니라 기능이 작동함을 증명하는데 필요한 요청과 필드의 최소 집합을 정의하는 것입니다.
먼저 필요한 데이터와 그 출처를 나열하세요: 읽을 수 있는 기존 필드, 저장해야 하는 새 필드, 계산할 수 있는 값. 각 필드의 출처를 명확히 할 수 없다면 계획이 아직 완전하지 않습니다.
API 표면은 작게 유지하세요. 많은 기능에서 하나의 읽기와 하나의 쓰기면 충분합니다:
GET /items/{id}는 화면을 렌더링하는 데 필요한 상태를 반환POST /items/{id}/update는 사용자가 변경할 수 있는 항목만 허용하고 업데이트된 상태를 반환입출력을 문단 대신 평문 객체로 작성하세요. 필수 vs 선택 필드와 흔한 오류(찾을 수 없음, 검증 실패)에 대한 동작을 포함하세요.
데이터베이스를 건드리기 전에 빠른 인증 검토를 하세요. 누가 읽고 쓸 수 있는지 한 문장으로 결정하세요(예: “로그인한 모든 사용자는 읽기 가능, 관리자만 쓰기 가능”). 이를 건너뛰면 재작업이 발생하기 쉽습니다.
마지막으로 무엇을 저장하고 무엇을 계산할지 결정하세요. 간단한 규칙: 사실(facts)은 저장하고, 뷰는 계산하세요.
Claude Code는 명확한 목표와 좁은 범위를 줄 때 가장 잘 작동합니다. 지저분한 요청과 제약(마감일, 영향을 받는 사용자, 데이터 규칙)을 붙여넣고 스코프된 출력으로 요청하세요:
응답을 받은 후 리뷰어처럼 읽으세요. “성능 개선”이나 “더 깔끔하게” 같은 문구가 보이면 측정 가능한 문구로 바꿔 달라고 요청하세요.
요청: “구독 일시 중지 기능 추가”
스코프된 버전은 이렇게 말할 수 있습니다: “사용자는 1~3개월 동안 일시 중지할 수 있으며 다음 청구일이 업데이트되고 관리자가 일시중지 상태를 볼 수 있다.” 아웃오브스코프: “정산(프라레이션) 변경 없음.”
여기서 커밋 계획은 실용적으로 변합니다: DB 및 API 형태 하나, UI 컨트롤 하나, 검증 및 오류 상태 하나, E2E 테스트 하나.
큰 변경은 버그를 숨깁니다. 작은 커밋은 리뷰를 빠르게 하고 롤백을 안전하게 하며 수용 기준에서 벗어날 때 이를 알아차리기 쉽게 만듭니다.
유용한 규칙: 각 커밋은 하나의 새로운 동작을 열어야 하고, 그것이 작동함을 증명할 빠른 방법을 포함해야 합니다.
일반적인 순서는 다음과 같습니다:
각 커밋을 집중적으로 유지하세요. “여기 왔으니” 하는 리팩터링을 피하세요. UI가 기본적이더라도 앱이 엔드투엔드로 동작하도록 유지하세요. 마이그레이션, 동작, UI를 하나의 커밋으로 묶지 마세요(명확한 이유가 있는 경우 제외).
이해관계자가 “보고서 내보내기 추가할 수 있나?”라고 하면 많은 선택이 숨겨져 있습니다: 어떤 보고서, 어떤 형식, 누가 내보낼 수 있는지, 전달 방식 등.
설계를 바꾸는 질문만 하세요:
답을 “Sales Summary 보고서, CSV-only, 매니저 역할, 직접 다운로드, 최대 90일”이라고 가정하면 v1 수용 기준은 구체적입니다: 매니저는 Sales Summary 페이지에서 Export를 클릭할 수 있고; CSV는 화면상의 테이블 열과 일치해야 하며; 필터를 존중해야 하고; 90일을 초과하면 명확한 오류를 보여주고; 최대 50k 행까지 30초 이내에 다운로드가 완료되어야 합니다.
최소 UI 계획: 테이블 액션 근처에 Export 버튼 하나, 생성 중 로딩 상태, 문제를 고치는 방법을 알려주는 오류 메시지(예: “90일 이하를 선택하세요”).
최소 API 계획: 필터를 받아 파일 응답으로 CSV를 반환하는 하나의 엔드포인트, 테이블과 동일한 쿼리를 재사용하며 서버측에서 90일 규칙을 적용.
그런 다음 몇 개의 촘촘한 커밋으로 배포하세요: 먼저 고정된 해피패스용 엔드포인트, 그다음 UI 연결, 그다음 검증 및 사용자용 오류, 마지막으로 테스트 및 문서.
“팀 역할 추가” 같은 요청은 초대, 편집, 기존 사용자에게 무슨 일이 일어나는지에 대한 규칙을 숨기곤 합니다. 추측하고 있다면 가정을 문서화하고 질문으로 바꾸거나 명백한 규칙으로 만드세요.
작업 하나에 “작동하게 만들기”와 “예쁘게 만들기”를 함께 넣으면 며칠을 잃습니다. 첫 작업은 동작과 데이터에 집중하세요. 스타일링, 애니메이션, 간격 조정 등은 필요하지 않다면 후속 작업으로 미루세요.
엣지 케이스는 중요하지만 모두를 즉시 해결할 필요는 없습니다. 신뢰를 깰 수 있는 몇 가지(중복 제출, 충돌 편집 등)는 처리하고 나머지는 명확히 보류하세요.
적어두지 않으면 놓칩니다. 수용 기준에 최소 하나의 언해피 패스와 최소 하나의 권한 규칙을 포함하세요.
“빠르다”나 “직관적이다” 같은 표현은 수치나 구체적 검증 방법이 없다면 피하세요. 리뷰에서 증명할 수 있는 것으로 바꾸세요.
동료가 정신을 읽지 않고도 리뷰하고 테스트할 수 있게 과제를 고정하세요:
예: “저장된 검색 추가”는 “사용자가 필터를 저장하고 나중에 다시 적용할 수 있다”가 되며, 비목표는 “공유 없음”, “정렬 변경 없음”.
스코프된 작업을 얻었으면 그것을 보호하세요. 코딩 전에 요청한 사람들과 빠른 상식 검토를 하세요:
그런 다음 기준을 티켓과 PR 설명, 팀이 실제로 보는 곳에 저장하세요.
Koder.ai (koder.ai)에서 빌드한다면 먼저 계획을 고정한 다음 코드 생성을 시도하는 것이 도움이 됩니다. Planning Mode는 그 워크플로에 적합하고, 실험이 필요할 때 시도하고 되돌릴 수 있게 스냅샷과 롤백이 안전 장치가 됩니다.
빌드 중 새로운 아이디어가 떠오르면 범위를 안정적으로 유지하세요: 아이디어를 후속 목록에 적고, 수용 기준을 바꿀 만큼 큰 변경이면 재스코핑을 잠깐 멈추고, 각 커밋을 하나의 기준에 묶어 진행하세요.
Start by writing the outcome in one sentence (what the user can do when it’s done), then add 3–7 acceptance criteria that a tester can verify.
If you can’t describe the “correct” behavior without debating it, the task is still vague.
Use this quick format:
Then add one concrete example of the expected behavior. If you can’t give an example, replay the last time the problem happened and write what the user clicked and expected to see.
Write a short “Definition of done” list first (the checks that must pass), then a separate “Nice-to-have” list.
Default rule: if it’s not needed to prove the feature works end-to-end, it goes into nice-to-have.
Ask the few questions that change scope:
These force the missing decisions into the open.
Treat edge cases as scope items, not surprises. For v1, cover the ones that break trust:
Anything else can be explicitly deferred as out-of-scope notes.
Use testable statements anyone can run without guessing:
Include at least one failure case and one permission rule. If a criterion can’t be tested, rewrite it until it can.
Name the exact screens and the one visible change per screen.
Also list the required UI states:
Keep copy (button text, errors) in scope too, even if it’s placeholder text.
Keep the contract small: usually one read and one write is enough for v1.
Define:
Store facts; compute views when possible.
Ask for a boxed deliverable:
Then re-prompt any vague wording like “make it cleaner” into measurable behavior.
Default sequence:
Rule of thumb: one commit = one new user-visible behavior + a quick way to prove it works. Avoid bundling “while I’m here” refactors into the feature commits.