make-it-work

아이디어부터 배포까지: 컨텍스트 스킬을 통해 코드베이스를 AI 친화적으로 만들고, 요구사항을 구체화하며, 작업을 분할하고, 구현 계획을 세우며, 요구사항 및 코드베이스 가이드에 따라 변경 사항을 검토하거나, implement 기능을 사용하여 티켓 전체 흐름을 오케스트레이션하세요.

대규모의 복잡한 코드베이스를 다루는 엔지니어링 팀을 위해 구축되었습니다. 그린필드(greenfield) 사이드 프로젝트용이 아닙니다. 코드베이스에 이력, 도메인 규칙, 레거시 결정 사항이 내재되어 있을 때, 단순히 '일반적으로 똑똑함'으로는 충분하지 않습니다. Claude는 당신의 프로젝트를 알아야 합니다.

문제점

Claude는 코드를 잘 읽습니다. 하지만 대규모의 장기간 유지된 코드베이스에서는 사소한 것들을 놓칩니다. 오래된 커밋에 묻힌 도메인 규칙, 문서화되지 않은 암묵적 제약 사항, 여러 계층에 걸쳐 분산된 비즈니스 로직 같은 것들입니다. Claude는 추측합니다. 리포지토리가 클수록 상황은 더 나빠집니다.

make-it-work는 이 문제를 근본적으로 해결합니다.

작동 방식

/make-it-work:go-deep

go-deep은 코드베이스를 매핑하고, Claude가 작업을 수행하기 전에 로드하는 구조화된 지식 기반을 구축합니다:

• 어떻게(How)와 무엇(What) (항상 로드됨) - 두 개의 규칙 파일이 있습니다. architecture.md는 어떻게에 관한 것(도메인, 컴포넌트, 코드 영역)이고, product.md는 무엇에 관한 것(사용 사례, 액터, 비즈니스 규칙)입니다.
• 스킬 (Skills) (필요할 때 로드됨) - 기능별 도메인당 하나씩, 사용 사례별로 하나씩 존재합니다. 각 스킬은 코드의 한 영역에 대한 정확하고 최소한의 설명이며, Claude가 탐색하기에는 충분하지만 컨텍스트를 부풀리지는 않습니다.

교차 참조 맵 (Cross-reference map)

모든 도메인 스킬은 영향을 받는 사용 사례를 가리킵니다. 모든 사용 사례 스킬은 접촉하는 도메인을 가리킵니다. Claude는 이러한 교차 참조를 자동으로 사용합니다. 기능을 계획할 때 관련된 도메인이 무엇인지 이해하기 위해 링크를 따르고; 테스트를 계획할 때는 도메인 변경으로 영향을 받는 사용 사례를 추적하여, 직접 매핑하지 않아도 진행 및 회귀(regression)를 커버합니다.

컨텍스트 효율성

스킬 설명은 최소한이면서도 정확하게 작성됩니다. Claude는 설명을 읽고 스킬을 로드할지 결정하며, 필요 없는 정보는 절대 가져오지 않습니다. 코드베이스가 클수록 이것이 더욱 중요합니다: Claude는 현재 작업에 필요한 정확한 컨텍스트만 얻으며, 그 이상은 없습니다. 계획하든 실행하든 환각(hallucinating)이나 오해석을 하지 않습니다.

동기화 유지하기 (Staying in sync)

go-deep가 구축하는 부분 중 하나는 CLAUDE.md에 포함된 강력한 강제 규칙입니다: 커밋하기 전에 Claude는 어떤 스킬이나 문서가 업데이트되어야 하는지 확인합니다. 새로운 도메인이 있나요? 스킬을 만드세요. 기존 도메인이 변경되었나요? 업데이트하세요. 지식 기반이 코드와 동기화되지 않은 상태로는 아무것도 배포되지 않습니다.

프로젝트에 온보딩할 때 go-deep를 한 번 실행하세요.

코드가 알려줄 수 없는 것 (What the code can't tell you)

go-deep 과정 동안 Claude는 목표 지향적인 질문을 하여, 어떻게(how)와 무엇(what) 파일이 코드만 읽어서 배울 수 없는 내용을 포착하게 합니다. 이는 Claude에게 단순히 구조뿐 아니라 프로젝트 전체의 그림을 제공합니다.

질문 단계에서는 Claude가 귀하의 코드에 대해 오해하는 부분을 밝혀냅니다: 파일들을 읽는 것만으로는 명확하지 않은 도메인 개념, 개발자들의 머릿속에만 존재하는 비즈니스 규칙, 그리고 문서화된 적이 없는 아키텍처에 내재된 가정들입니다. 이 질문들에 답하면 정적 분석(static analysis) 도구가 생성할 수 없는 문서를 얻게 됩니다: 무엇 뒤에 숨겨진 왜입니다.

생성되는 스킬들은 Claude Code 외부에서도 유용합니다. 제품 관리자들은 도메인 및 사용 사례 스킬을 읽고 시스템이 실제로 무엇을 하는지 이해하여, 요구사항 작성을 위한 살아있는 진실의 원천(live source of truth)으로 활용할 수 있습니다.

---

define-test-strategy는 go-deep 이후의 온보딩 단계입니다. 이 단계는 하나의 리포지토리의 테스트 전략(test-strategy) 스킬, 즉 .claude/skills/test-strategy/SKILL.md를 구축합니다. 이 스킬은 해당 리포지토리의 테스트가 어디에 위치하는지—별도의 QA 자동화 리포지토리에 있는 경우 등 다른 리포지토리에도 포함됨—각 테스트 스위트를 어떻게 실행해야 하는지, 그리고 무엇이 필요한지(환경 변수(env vars), 서비스(services), CI 전용 스위트(CI-only suites))를 기록하며, 각 계층의 새로운 테스트가 어디에 속하는지를 명시합니다. 이 과정은 기존 테스트에 리포지토리 한정형 @covers <repo>:UC-<id> <repo>:domain-<name> 주석을 태그로 추가하는데, 이는 검토를 위해 커밋되지 않은 상태로 남겨둡니다. 또한 CLAUDE.md 스킬 참조(Skills Reference)에 /test-strategy라는 단일 행을 추가합니다. 마지막으로 해당 태그들로부터 실시간으로 계산된 커버리지 보고서가 생성됩니다. 언제든지 다시 실행하고

⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

run-regression은 프로젝트의 회귀(regression) 테스트 스위트 전체를 실행합니다. 이 스위트는 전체 스위트(full:<repo>), 단일 리포지토리의 스위트(full:<repo>), 또는 repo-한정 사용 사례 및 도메인 토큰으로 태그된 테스트(예: payments-api:UC-08, payments-api:domain-velocity)를 실행할 수 있습니다. 하나의 호출로 여러 리포지토리에 대한 토큰을 혼합하여 사용할 수 있습니다. 이 명령어는 각 리포지토리의 테스트 전략 스킬을 사용하여 테스트 위치, 명령 및 전제 조건을 읽고, 모든 위치(다른 리포지토리 포함)에 있는 @covers 주석을 검색하여 태그가 지정된 테스트를 찾습니다. 또한, 리포지토리에 전략이 없는 경우 package.json/Makefile/CI 발견 기능을 활용하여 전체 스위트를 실행합니다. 단순히 full만 실행할 경우 각 리포지토리의 자체 스위트만 실행됩니다. 로컬에서 실행할 수 없는 스위트(CI 전용, 환경 변수나 서비스 누락, 리포지토리에 테스트 없음)는 실패가 아닌 '실행 안 함'으로 보고됩니다. 결과는 채팅창에 실시간으로 보고되며 디스크에 영구 저장되지 않습니다.

일상적인 개발 과정에서 변경 사항을 회귀 스위트(전체 또는 범위 지정)와 비교하여 확인하는 데 직접 사용할 수 있습니다. 또한, 자체 테스트 실행 로직을 작성하는 대신, 계획의 마지막 단계에서 공유 구현체인 execute가 완료 게이트로 호출하는 기능입니다.

---

/make-it-work:shape-the-epic

Product 또는 기술 부채(Technical-debt) 모드에서 모든 작업 관리 도구(Jira, Azure DevOps, Linear, Shortcut)를 위한 에픽(epic)을 구성합니다. 집중할 준비 상태 카테고리를 선택한 다음, 발견 인터뷰와 격차 확인(gap-check) 과정을 거칩니다. 인터뷰 후에는 범주별 콘텐츠 승인 라운드를 거치지 않고 통합된 피드백을 위해 전체 마크다운 에픽을 직접 생성합니다. 실제 미확인 항목은 범위가 지정된 TBD(To Be Determined)로 유지되며, 선택되지 않은 카테고리는 **평가 안 됨(Not assessed)**으로 표시됩니다.

제품 모드(Product mode)는 가치 제안, 사용자 및 권한, 핵심 성과 지표(KPI), 사용 사례, 출시 계획, 그리고 완료 여부를 다룹니다. 기술 부채 모드(Technical-debt mode)는 증거와 영향력, 원하는 결과, 테스트 가능한 인수 기준(acceptance criteria), 검증, 그리고 범위 경계에 중점을 둡니다. 합의된 제약 조건이나 외부 종속성은 선택 사항입니다. 이 기능은 소유권을 수집하지 않으며, 구현 계획은 기본 기술 부채 에픽(technical-debt epic) 외부에 있습니다. --autopilot은 선택 및 인터뷰 질문을 자동으로 해결하고 감사 로그(audit log)를 추가합니다.

/make-it-work:slice-the-epic

요구사항, 에픽, 티켓 또는 사용자 스토리를 작고 독립적으로 배포 가능한 증분으로 분할하며, 각 슬라이스마다 적절한 Gherkin(Given/When/Then) 사용자 스토리로 작성합니다. 기능적(functional), 워크플로우(workflow), 데이터(data), 사용자 역할(user role), 또는 기술 위험(technical-risk slicing)의 슬라이싱 기법을 선택하고, 각 슬라이스의 크기를 스프린트 절반 이하로 조정하며, 위험도 순으로 정렬합니다.

티켓이나 에픽이 너무 커서 스프린트 규모의 스토리로 분할되어야 할 때 사용합니다.

find-the-repos는 먼저 티켓의 정확한 식별자(identifiers), 엔드포인트(endpoints), UI 레이블이 이미 존재하는지 확인하여, 구현체가 발견되면 verify and finish 보고서로 시작합니다. 그런 다음 문서(docs), 도메인/사용 사례 기술(domain/use-case skills), 그리고 경계가 지정된 코드 검색(bounded code searches)을 사용하여 리포지토리(repos)를 추려냅니다. 특정 코드 증거만으로도 Definite를 확립할 수 있습니다. 워크스페이스 감지(Workspace detection)는 카탈로그 메타데이터, 리포지토리 목록, 워크스페이스 설정뿐만 아니라 CLAUDE.md 파일도 받아들입니다. 그룹화 메타데이터가 없는 대형 형제 리포지토리(sibling-repo) 워크스페이스에서도 기본적으로 모든 리포지토리를 평가하며, 별도의 리포지토리 선택 단계는 필요하지 않습니다. 사용자는 범위를 명시적으로 좁힐 수 있습니다. 실제 워크스페이스/범위 선택은 사용 가능한 경우 AskUserQuestion을 사용하여 거대한 체크박스 목록 없이 이루어집니다. 모든 평가 세부 정보, 소유권 출처/충돌(ownership sources/conflicts), 외부 라우팅은 하나의 보고서, <TICKET>-repos.md,에 담겨 있으며, 댓글, 수정 사항 및 확인 업데이트는 동일한 파일을 사용합니다. 터미널에는 지원 유형인 product.md, architecture.md, context skills, 그리고/또는 code와 함께 간결한 Definite 리포지토리 / 소유자(Owner) / 증거(Evidence) 테이블만 표시되며, 보고서 링크와 검토 프롬프트가 추가됩니다. 붙여넣은 티켓은 관련 티켓 키를 빌리지 않고 임시 슬러그(provisional slug)를 사용할 수 있습니다.

고정된 close-the-gaps → plan-the-work → execute → review-the-pr 파이프라인과 달리, find-the-repos는 독립적으로 작동합니다. 이 플러그인에서 아직 아무것도 호출하지 않기 때문에, 그 파이프라인이 시작되기 전에, 또는 티켓의 홈 리포지토리가 이미 명확하지 않을 때 언제든지 단독으로 실행할 수 있습니다.

---

close-the-gaps는 개발이 시작되기 전에 제품 분석가(Product Analyst) 역할을 수행합니다. 이 도구는 티켓과 관련된 프로젝트 기술을 로드하고, 영향을 받는 코드 깊숙이 파고들어 모든 격차(gap)를 표면화합니다. 여기에는 모호한 언어, 누락된 엣지 케이스(edge cases), 상충되는 요구사항, 명시되지 않은 가정 등이 포함됩니다. 그런 다음 질문 하나하나씩 사용자에게 안내합니다. 또한 **오프라인 모드(offline mode)**로 실행할 수도 있습니다. 이 경우 모든 질문을 파일로 내보내 세션 외부에서 답변한 후, 해당 파일을 가리키며 다시 호출하여 답변을 주입하고 작업을 재개할 수 있습니다. 이는 실시간으로 답변해 줄 사람이 없을 때 유용합니다.

출력물은 Gherkin 형식에 적합하게 다듬어진 명세서(spec)입니다. 알려지지 않은 미지(unknown unknowns)가 명시적으로 드러납니다. 코드가 단 한 줄도 작성되기 전에 요구사항이 견고해집니다.

팀들은 정제 회의(refinement meetings) 전에 이 도구를 사용합니다. 이를 통해 개발자들이 논의 중간에 격차를 발견하는 대신, 집중된 질문을 가지고 도착할 수 있습니다. 또는 출력물을 Jira 티켓에 직접 게시하여 제품 담당자가 비동기적으로 검토하게 할 수도 있습니다. 간단한 티켓의 경우 회의가 필요 없습니다.

모호한 티켓이 초래하는 비용은 재작업(rework)으로 지불됩니다. close-the-gaps는 첫 줄의 코드가 작성되기 전에 이러한 격차를 메워줍니다.

---

/make-it-work:plan-the-work

합의된 명세(spec)나 다듬어진 티켓을 실제 프로덕션 코드가 작성되기 전에 실행 가능한 구현 계획으로 변환합니다. 프로젝트의 가이드라인과 관련 기술 스킬을 로드하고, 하나 이상의 리포지토리 전반에 걸친 실제 코드 경로를 조사하며, 사용자님과 함께 기술적 및 범위상의 격차(gap)를 메우고, make-it-work/<TICKET>/<TICKET>-plan.md 파일로 원자적이고 검증 가능한 계획을 작성합니다. 대상 프로젝트가 테스트 프레임워크를 구성한 경우, 필요한 곳에 최소한의 명확하게 표시된 스텁 시그니처(stub signatures)를 타입이 지정되거나 동적 스택에 남겨두어 유효한 런타임 빨간 상태(red state)에 도달하는 과정과 회귀 테스트(regression tests) 진행 상황을 기록하고 확인합니다 (빨강). 이 파일들은 커밋되지 않은 채 작업 트리에 남아 있습니다. 테스트 전략(test-strategy) 스킬을 사용하는 경우, 새로운 테스트는 전략이 지시하는 곳에 @covers 태그와 함께 추가되고, 이를 받는 QA 리포지토리는 테스트 범위로 계획에 포함됩니다. 또한 이 계획은 회귀 게이트(regression gate)를 위해 건드린 도메인과 사용 사례도 기록합니다.

티켓 ID나 명세 경로를 전달하거나, 스킬이 현재 브랜치에서 티켓을 파생하도록 할 수 있습니다. 다른 엔지니어 또는 에이전트가 추측하지 않고 작업을 단계별로 실행할 수 있도록 close-the-gaps 이후와 구현 전에 사용합니다.

/make-it-work:execute

이미 작성된 계획(plan)인 plan-the-work을 따라 단계별로 구현합니다. 각 단계의 코드를 작성하고, 도움을 요청하기 전에 해당 단계의 테스트가 통과할 때까지 5회 시도 재시도 제한으로 다시 실행하며, 실패한 테스트가 단순한 테스트 버그가 아니라 실제 제품 동작에 대한 질문처럼 보일 때는 추측하는 대신 전체 계획을 중단합니다. 모든 단계가 성공적으로 완료되면, 이를 최종 검증 게이트(completion gate)로 삼아 run-regression을 실행합니다. 이 과정에는 계획이 건드린 도메인/사용 사례 태그가 붙은 모든 레포의 테스트와, 계획이 변경한 각 레포 전체 스위트가 포함됩니다. 만약 계획이 토큰 기록이 없거나 어떤 레포도 테스트 전략을 가지고 있지 않다면 전체 스위트를 실행하며, 게이트 실패 시 자동 수정하려 하기보다 사용자의 검토를 위해 멈춥니다. 이 과정에서 절대로 사용자 대신 커밋하지 않아 모든 완성된 작업은 사용자가 검토할 수 있도록 워킹 트리(working tree)에 남겨둡니다.

티켓 ID나 계획 파일의 경로를 전달하거나, 스킬이 현재 브랜치로부터 티켓을 유추하도록 할 수 있습니다. 이 기능을 plan-the-work 이후에 사용하여 실행 준비가 된 계획을 실제 코드로 변환하고, close-the-gaps → plan-the-work → execute → review-the-pr 파이프라인을 완성합니다.

/make-it-work:review-the-pr