execute은(는) 무엇을 하나요?
완전한 작업 단위를 실행하세요: 계획하고, 구축하고, 실제 결과를 검증하고, 커밋합니다.
호출 위치
이는 /prd-to-issues가 구체적인 슬라이스를 생성한 후 또는 사용자가 이미 명확히 범위가 지정된 구현 작업을 가지고 있을 때 사용되는 주요 파이프라인 스킬입니다.
작업을 구축, 검증, 커밋할 준비가 되었을 때 /execute를 사용하세요.
슬라이스에 여전히 활성 사용자 판단, 감독 또는 구현 결정 중 수락 결정이 필요한 경우 HITL /execute를 사용하세요. 다음 슬라이스가 이미 GitHub에서 내구성이 있고, 차단되지 않았으며, 해당 이슈, 경계 맵, 링크된 리서치 아티팩트(아카이브 파일 또는 스파이크 이슈) 또는 docs/solutions/ 컨텍스트에서 읽을 수 있을 때만 AFK /execute를 사용하세요.
그것을 전혀 알지 못하는 독자가 읽을 수 있어야 합니다 — 이것이 AFK 반복의 의미입니다. /prd-to-issues §4의 컨텍스트 완전성 검사는 그 조건 뒤에 있는 게이트입니다. 이는 모든 AFK 슬라이스가 이슈가 제출되기 전에 ### Context 블록 또는 명시적인 빈 선언을 포함해야 합니다. 이러한 블록 없이 AFK로 표시된 슬라이스는 이 조건에 대해 확인된 적이 없으며, 충족된다고 가정된 것입니다. 이를 형식적으로 통과시키는 것이 아니라 HITL로 실행하거나 /prd-to-issues로 다시 보내야 하는 이유로 취급하세요.
아래의 0단계: 전제 조건에서 필수 Ralph 자동 감지 및 TDD 마커 게이트를 확인하세요.
문제나 형태가 아직 해결되지 않은 경우 /shape, /research, 또는 /write-a-prd를 대체하는 데 사용하지 마세요. 구현이 완료되고 검토 준비가 되면 /pre-merge의 대체품으로 사용하지 마세요.
워크플로
0. 전제 조건
브랜치 격리 게이트. 구현 작업 전에, 이전 작업의 남은 기능 브랜치가 아닌 이 특정 작업을 위해 생성된 깨끗한 브랜치에서 작업하고 있는지 확인하세요.
격리가 이미 제공됨 — 대기 (먼저 확인, 번호가 매겨진 규칙보다 먼저). 일부 환경은 /execute가 실행되기 전에 세션에 전용 격리된 워크트리+브랜치를 제공합니다 — Conductor 워크스페이스, GitHub Codespaces, devcontainers 등 각각 "하나의 워크스페이스 = 하나의 브랜치, 기본에서 자동 포크"를 프로비저닝하고 설정 스크립트가 이미 실행되었습니다. 그런 경우 파이프라인은 프로비저닝을 소유하지 않습니다: 여기서 워크트리를 생성하면 호스트의 워크트리 안에 중첩되고, 호스트의 브랜치(작업이 아닌 워크스페이스 이름 지정)는 "오래된" 것이 아닙니다. 환경의 신호를 읽고 워크트리를 이미 소유한 사람에게 양도하세요(Norman — 파이프라인이 항상 프로비저닝한다는 머리 속 가정 대신 세계의 표시자를 읽으세요; Meadows — 주식당 하나의 행위자, 따라서 파이프라인은 경쟁 관리자를 추가하는 대신 양보합니다).
.claude/settings.json worktree.provisioning에서 프로비저닝 모드를 확인하세요 — "host" | "pipeline" | "auto", 키가 없으면 기본값 "auto"(기존 research.storage 선례를 미러링).
host— 격리는 호스트 소유. 무조건 대기.pipeline— 파이프라인이 프로비저닝. 이 대기를 건너뛰고 아래 번호가 매겨진 게이트를 실행.auto(기본값) — 두 신호 중 하나라도 발생하면 대기:- 호스트 환경 변수가 이 트리를 설명함 — 아래 블록은
host_owned=yes를 출력합니다. 이것이 가장 저렴하고 기본적인 판별자입니다: 파이프라인의 유일한 감지 메커니즘은 Bash이며, 이러한 변수는 에이전트의 셸에서 볼 수 있습니다. 존재만으로는 충분하지 않습니다:CONDUCTOR_WORKSPACE_PATH는 Conductor에서 시작된 모든 셸에서 상속되며 다른 저장소의 워크스페이스를 지정할 수 있으므로 현재 최상위 디렉토리를 포함하는 경우에만 계산됩니다. (cwd의.conductor디렉토리를 통해 감지하지 마세요 — Conductor는 워크스페이스가 아닌$CONDUCTOR_ROOT_PATH아래에 보관합니다.) - 현재 작업 트리가 저장소의 기본 작업 트리가 아님 —
git rev-parse --show-toplevel이git worktree list --porcelain의 첫 번째 경로와 다릅니다.
- 호스트 환경 변수가 이 트리를 설명함 — 아래 블록은
# host-signal: 호스트 환경 변수가 이 셸뿐만 아니라 이 트리를 설명합니까?
host_owned=no
top=$(cd "$(git rev-parse --show-toplevel)" && pwd -P)
if [ -n "${CONDUCTOR_WORKSPACE_PATH:-}" ]; then
ws=$(cd "$CONDUCTOR_WORKSPACE_PATH" 2>/dev/null && pwd -P) || ws=
if [ -n "$ws" ]; then
case "$top/" in "$ws"/*) host_owned=yes ;; esac
fi
fi
if [ -n "${CODESPACES:-}" ] || [ -n "${REMOTE_CONTAINERS:-}" ]; then host_owned=yes; fi
echo "host_owned=$host_owned"
CODESPACES 및 REMOTE_CONTAINERS는 비교할 경로가 없으며 존재 여부로 읽습니다. 컨테이너 범위이므로 이를 보는 셸은 설명하는 저장소가 있는 컨테이너 내부에 있습니다. 동일한 블록이 /closeout, /lfg, /init-pipeline에 나타나며, 팩 자체 저장소의 scripts/test-host-signal-containment.sh에 의해 고정된 바이트 동일합니다.
대기할 때: 워크트리 생성 및 EnterWorktree를 건너뛰고 현재 브랜치에서 그대로 작업하세요. 아래 번호가 매겨진 규칙은 이미 충족되었습니다 — 특히 규칙 3은 적용되지 않습니다 (호스트 프로비저닝 브랜치는 기본도 작업 이름도 아니지만 오래된 것이 아닙니다. 워크트리를 중첩하지 말고 중지하지 마세요). 호스트는 이미 git-무시된 구성과 종속성을 시드했으므로 "워크트리 설정 체크리스트"의 대부분은 정보 제공용입니다 — 명령이 실패하면 .env.local/종속성을 점검하지만 다시 프로비저닝하지 마세요. git-hooks 항목은 예외이며 여전히 적용됩니다. 호스트는 추적된 파일과 종속성을 프로비저닝합니다. git 훅은 .git/hooks에 있으며, 이는 워크트리별로 있고 추적되지 않으므로 호스트 프로비저닝 워크스페이스에는 일반적으로 훅이 없습니다. 대기할 때도 해당 항목을 확인하세요. 이슈-형태 게이트로 진행하세요.
이 대기는 의도적으로 /closeout의 정리 확인과 비대칭입니다. 유입(Inflow)은 "이미 격리되었습니까?"라는 질문에만 답하면 됩니다 — 일반 감지(최상위 ≠ 기본) 및 환경 변수 힌트가 각각 이를 결정합니다. 유출(Outflow) 질문 — "누가 정리를 소유합니까?" — 더 엄격하며 일반적인 발견법에만 의존할 수 없습니다. 파이프라인으로 만든 워크트리도 최상위 ≠ 기본을 충족하기 때문입니다. /closeout은 명시적 설정 또는 호스트 환경 변수만을 기준으로 합니다.
- 현재 브랜치 확인:
git branch --show-current - 현재 브랜치가 기본 브랜치(예:
main,prod,master)인 경우 이 작업을 위한 새 기능 브랜치를 생성합니다. - 현재 브랜치가 다른 기능 브랜치(기본 브랜치도 아니고 이 작업 이름의 브랜치도 아님)인 경우 이전 작업의 오래된 브랜치에 있습니다. 여기에 새 작업을 커밋하지 마세요. 예외: 현재 브랜치가 이 작업의
Consumes from #N선언에 명명된 형제 슬라이스 브랜치인 경우 스택 PR 슬라이스를 위해 의도적으로 분기하려는 것입니다 — 진행하세요. 예외 (호스트 프로비저닝): 위의 대기 확인이 실행된 경우 이 브랜치는 호스트의 격리된 워크스페이스 브랜치입니다 — 오래된 것이 아닙니다. 그대로 작업하세요.
격리된 브랜치를 생성하려면 다음 접근 방식 중 하나를 사용하세요(선호도 순):
- Worktrunk (
wt을 사용할 수 있는 경우):wt switch --create <branch-name>— 적절한 기본에서 새 워크트리 + 브랜치를 생성하고 전환하여 완전한 파일 시스템 격리를 제공합니다. 지침은/worktrunk스킬을 사용하세요. - Plain git:
git checkout <base> && git checkout -b <branch-name>— 현재 작업 디렉토리의 적절한 기본에서 새 브랜치를 생성합니다.
적절한 기본은 기본적으로 저장소 자체의 기본 브랜치입니다 — bash "$SC" base-ref --name이 출력하는 것(SC는 이 스킬의 references/sidecar.sh로 설정). main을 가정하지 마세요. 이 슬라이스에서 가져온 기호를 생성하는 병합되지 않은 Consumes from #N 종속성이 있는 슬라이스의 경우 대신 해당 형제 슬라이스의 브랜치에서 분기하여 스택 PR이 형제의 PR을 대상으로 지정할 수 있도록 합니다(Hammant Trunk-Based Development Ch. 13: 스토리당 여러 PR; 형제의 PR은 여전히 2일 이내에 저장소의 기본 브랜치로 병합되어야 함).
작업에서 브랜치 이름을 파생합니다: 예: issue-5-landing-page, landing-page 또는 이슈 슬러그. 이전 작업의 브랜치 이름을 재사용하지 마세요.
세션으로 워크트리에 진입합니다(워크트리를 생성한 경우). 워크트리를 생성하는 것은 세션이 내부에서 실행되는 것과 같지 않습니다 — wt switch --create는 각 명령 후 셸 cwd를 프로젝트 루트로 재설정하므로 추가 단계 없이 세션은 원래 체크아웃에 고정되고 보고된 cwd는 작업이 발생하는 위치에 대해 거짓말을 합니다. 워크트리를 생성한 후, 하네스 EnterWorktree 도구로 진입하여 세션의 작업 디렉토리가 진정으로 워크트리인지 확인하세요:
EnterWorktree { path: <absolute-worktree-path> }를 호출합니다. 경로는 이 저장소의git worktree list에 이미 나타나야 합니다(방금 생성했으므로 나타납니다). 이는 세션을 지속적으로 워크트리로 전환합니다.- 생성 단계를 정확히 위와 같이 유지하세요 —
wt switch --create/git worktree add는.env.local과 종속성을 시드하는 worktrunkpre-start훅을 실행합니다.EnterWorktree는 cwd만 전환합니다. 해당 훅을 실행하지 않습니다. 먼저 생성(env/종속성을 시드하기 위해)한 다음 진입하세요. - 이는 지식을 머리가 아닌 세상에 둡니다: cwd는 편집 및 커밋이 어디에 도착하는지에 대한 진실을 알려주며(지켜보는 운영자가 볼 수 있음), 잊어버릴
cd접두사가 없으므로 접두사가 없는 명령이 잘못된 트리에 쓰는 미끄러짐 클래스를 제거합니다. - Plain git 옵션(
git checkout -b, 워크트리 없음)은 현재 체크아웃에 브랜치를 생성합니다 — 진입할 워크트리가 없으므로EnterWorktree를 건너뛰고 그대로 작업하세요.
AFK / 헤드리스 폴백. EnterWorktree를 사용할 수 없는 경우(헤드리스 실행, AFK Ralph, cron), cwd-접두사 규율로 폴백: Bash 명령 후 셸 cwd가 프로젝트 루트로 재설정되므로 이 세션의 모든 Bash 호출 앞에 cd <absolute-worktree-path> &&를 접두사로 붙입니다. 하네스 도구를 진정으로 사용할 수 없는 경우에만 사용하세요 — 기본 메커니즘이 없는 환경을 위해 유지된 이전 해결 방법입니다.
이 워크트리의 정리는 파이프라인 꼬리의 /closeout이 소유합니다 — PR이 병합된 후 /closeout은 셸을 기본 체크아웃으로 다시 고정하고 워크트리를 제거하고 병합된 브랜치를 정리합니다. /execute는 워크트리 수명 주기의 유입 측면입니다. /closeout은 유출 측면입니다. 아래의 6단계 정리는 .tdd-* 마커만 제거합니다 — 의도적으로 워크트리를 제거하지 않습니다.
워크트리를 생성한 후 설정합니다. 새 워크트리는 추적된 파일을 상속하지만 git-무시된 파일(.env.local, 워크트리별 종속성, 빌드 캐시)은 상속하지 않습니다. 두 가지 경로:
선호 — worktrunk 훅을 통해 한 번 구성 (프로젝트의 .config/wt.toml):
[pre-start]
copy = "wt step copy-ignored"
install = "pnpm install"
pre-start 훅은 차단됩니다 — 완료될 때까지 워크트리가 준비된 것으로 보고되지 않습니다. .env.local 또는 node_modules가 필요한 후속 명령이 훅과 경합할 수 있으므로 둘 다에 post-start(아님) pre-start를 사용하세요. 전체 레시피는 /worktrunk를 참조하세요. 프로젝트당 한 번.
폴백 — 일반 git worktree add에 대한 수동 설정 (worktrunk 없음):
cp <source-repo>/.env.local <worktree>/.env.local(및 프로젝트에서 사용하는 기타 git-무시된 구성).- 워크트리에서 프로젝트의 설치 명령(
pnpm install,npm ci,pip install -r requirements.txt등)을 실행합니다.
워크트리 설정 체크리스트 (DO-CONFIRM — 각 단계를 수행한 다음 진행하기 전에 확인). 워크트리가 생성된 방식에 관계없이 적용:
- Git-무시된 구성 복사됨 —
.env.local(및 기타.env.*,*.local또는 프로젝트별 무시된 구성)이 워크트리에 존재 - 종속성 설치됨 — 설치 명령(
pnpm install,npm ci등)이 워크트리에서 오류 없이 실행됨 - 세션이 워크트리 내부에 있음 —
pwd가EnterWorktree { path }를 통해 진입했기 때문에 워크트리 경로를 보고합니다(프로젝트 루트 아님). AFK/헤드리스 폴백에서만 이 항목은 대신cd <absolute-worktree-path> &&접두사가 모든 Bash 호출에 적용되고 있음을 의미 -
$CLAUDE_PROJECT_DIR범위 올바름 — 프로젝트가 스크립트에서 이 환경 변수를 참조하는 경우 기본 저장소가 아닌 워크트리 경로로 확인되는지 확인 - 로컬 git 훅이 설치되고 해당 관리자가
PATH에 있음 —ls "$(git rev-parse --git-dir)/hooks/" | grep -v '\.sample$'가 무언가를 나열하고 저장소가 선언한 관리자(lefthook,husky,pre-commit, …)가 확인됨. 훅은.git/hooks에 있으며 이는 워크트리별이고 추적되지 않음이므로 새 워크트리는 훅을 전혀 상속하지 않습니다 — 그리고 실패는 최악의 방향으로 조용합니다: 모든 커밋이 성공하고 저장소가 커밋 시 문서화하는 모든 보장이 단순히 실행되지 않습니다. 관리자가 없으면 설치(lefthook install)하거나 6단계 검토 노트에 이 브랜치에 대해 로컬 게이트가 비활성화되었음을 기록하여 아무도 녹색 로컬 실행을 병합 게이트로 읽지 않도록 합니다. - 분류 마커 없음 —
.claude/.tdd-active,.claude/.tdd-skipped,.claude/.lfg-active가 워크트리에 존재하지 않음(새 슬레이트; 3단계에서 하나 생성) - 검토 후 잠금 플래그 없음 —
.claude/.review-stamped및.claude/.fix-findings-active가 존재하지 않음. 둘 다 이전 브랜치의 검토에 속함:/pre-merge4단계가 첫 번째를 쓰고/fix-findings가 두 번째를 쓰며/closeout및/fix-findings가 각각 해당 브랜치의 끝에서 제거합니다. 누출된.review-stamped는 슬라이스가 시작되기 전에 모든 구현 쓰기를 거부합니다. 누출된.fix-findings-active는 전체 슬라이스 동안 잠금을 열어두는데 이는 조용한 방향입니다. 찾은 것을 삭제하세요 — 검토를 받지 않은 브랜치의 시작에 있으므로 둘 다 이것을 설명할 수 없습니다.
이슈-형태 및 블로커 게이트. 작업이 GitHub 이슈인 경우 구현하기 전에 취할 수 있는 슬라이스인지 확인하세요: 분해되지 않은 PRD가 아니고 차단되지 않았으며 다른 사람의 열린 PR에 의해 이미 종료되지 않았습니다. 하나의 GraphQL 읽기가 세 가지 모두에 답하며 블록이 결정합니다 — 눈으로 판단하지 마세요:
N=<n>
VERDICT_JQ='
def lines: split("\n")[];
[inputs][0] | if (.errors // [] | length) > 0 then "unknown" else
.data.repository.issue as $i
| if $i == null or $i.number != $n or (($i.title // "") == "")
or ($i.state != "OPEN")
or (($i.labels // []) | map(.name) | index("blocked"))
or (($i.linkedPullRequests // []).nodes // [] | length) > 0
or (($i.milestone // null) == null)
or (($i.milestone.state // "") != "OPEN") then "blocked"
else "clear" end
end'
gh api graphql -f query='
query($n: Int! $o: String! $r: String!) {
repository(owner: $o name: $r) {
issue(number: $n) {
number title state
labels(first: 20) { nodes { name } }
linkedPullRequests(first: 5) {
nodes { number state }
}
milestone { title state }
}
}
}
' -f n=$N -f o=$(gh repo view --json owner --jq .owner.login) -f r=$(gh repo view --json name --jq .name) --jq "$VERDICT_JQ"
"clear"만 진행을 허용합니다. "blocked"는 4단계로 건너뛰고 7단계에서 차단을 문서화합니다. "unknown"(API 오류, 권한 문제, 또는 이슈가 존재하지 않거나 GraphQL로 읽을 수 없음)도 차단으로 취급합니다. 슬라이스에 GitHub 이슈가 없는 경우(예: 작업이 이슈가 아닌 작업 항목인 경우) 이 게이트를 건너뛰고 작업의 범위를 명확히 하기 위해 다른 수단에 의존합니다.
GitHub 액세스 토큰이 gh CLI 인증을 통해 사용 가능한지 확인하세요. 이 마커 게이트를 통과하는 것만으로는 충분하지 않습니다: gh api는 GITHUB_TOKEN 또는 이미 인증된 세션(gh auth status)을 통해 인증을 확인합니다. 이 카드가 차단된 이슈를 넘어서는 경우 프로세스를 중지하고 사용자에게 보고합니다.
1. 계획
의도를 선언하세요. 이는 /execute가 작업의 범위를 명확히 하고 제약 조건을 식별하며 확인할 수 있는 결과를 정의하는 단계입니다. 단계 0(격리 설정)과 단계 3(마커 확인/쓰기) 사이의 모든 작업이 계획이라는 조치 가능한 데이터를 제공하는지 확인하세요.
- 이슈 또는 요청에서 작업 범위를 설명하세요. 이 작업이 담당하는 구체적인 경계는 무엇입니까? 경험상, 단일 구현 슬라이스는 단일 지점(라우트, 페이지, 컴포넌트, 백엔드 엔드포인트)이어야 하지만 지점의 모든 측면(데이터베이스 마이그레이션, 서비스 계층, 프레젠테이션, 오류 처리 및 로깅)을 포괄해야 합니다.
- 내부 _외부_에서 이 작업을 소비하거나 사용하는 기존 코드를 확인하세요. 작업의 공용 인터페이스에 대한 계약을 변경합니까? 변경 사항을 평가하고 계획하세요.
- 변경하지 않을 것과 이유를 문서화하세요. 이 범위 경계를 추론하고 명시적으로 표현하는 것은 AI 에이전트가 가장 약한 경향이 있는 부분입니다: 모든 것을 설명하는 대신 명시적으로 제외하세요.
- 작업의 계획된 산출물의 확립된 분류학을 참조하십시오:
docs/solutions/,docs/adr/, API 사양 파일, 데이터베이스 ERD 등. 백엔드 마이그레이션의 경우src/db/migrations/에 대해 이야기합니다. API 엔드포인트의 경우 해당 테스트 파일에 대해 이야기합니다. 프런트엔드 컴포넌트의 경우src/components/에 대해 이야기합니다. - 작업에 대해 관련이 있다고 알려진 제약 조건과 규칙을 식별하세요: 접근성 요구 사항, 성능 예산, 브라우저 지원, 보안 경계, 규정 준수 요구 사항.
- 코드의 어느 부분을 변경할 것인지(outline) 미리 결정하고 이를 잘못된 예측으로 문서화한 다음 실제로 수행된 작업과 비교하세요. 이는 작업의 "예측"을 생성하는 것을 의미할 수 있으며, 이는 종종 범위 확장을 조기에 발견하는 데 도움이 됩니다.
또한 이 단계는 작업 환경이 작업에 최적인지 확인하는 자연스러운 지점입니다:
- 언어 및 버전 관리자 —
.nvmrc,.tool-versions,.ruby-version등에 선언된 대로 올바른 언어 런타임이 설치되었는지 확인하세요.asdf,nvm,rbenv등의 표시기를 확인하세요. .claude/settings.json— 프로젝트 수준 설정이 환경에 대해 올바른지 확인하세요(예:research.storage는solutionsDir용이고,worktree.provisioning은 이 환경에 대해 올바른 모드로 설정됨).
기존 경계 맵 확인. 이슈는 ### Boundary map 섹션(이미 /prd-to-issues에 의해 기록됨)을 가지거나, docs/solutions/에 이미 존재하는 솔루션 문서를 참조하거나, 이 작업의 가장 좋은 설계를 문서화하기 위해 자체 솔루션 문서가 필요할 수 있습니다. 다음 순서로 확인하세요:
- 이슈 본문에
### Boundary map이 포함되어 있습니까? 그렇다면 맵 지식을 읽고 계획의 기반으로 사용하세요. - 이슈가
docs/solutions/의 솔루션 문서를 참조합니까? 그렇다면 그 문서를 로드하고 그 경계를 따르세요. - 그렇지 않은 경우
docs/solutions/<task-name>.md에 솔루션 문서가 이미 존재하는지 확인하세요. 존재하는 경우 로드하고 사용하세요. - 그렇지 않은 경우 빠른 경계 맵을 이슈에 제안하거나
docs/solutions/<task-name>.md에 직접 만드세요.
저장소 컨텍스트 로드. 이 작업과 관련된 파일과 디렉토리를 식별한 후 계속 진행하기 전에 이를 에이전트 컨텍스트로 로드하세요.
2. 방법 결정: TDD 적용 또는 건너뛰기
TDD 마커 확인. /prd-to-issues는 이슈에 ### TDD 선언을 기록했을 수 있습니다. 확인하세요:
grep -m1 '^### TDD' <<< "$(gh issue view <number> --json body --jq .body)" || echo "TDD marker not found"
또는 작업 항목의 자체 메타데이터를 확인하세요. TDD 마커가 존재하는 경우(예: "TDD: required", "TDD: recommended") 그 지침을 따르세요.
TDD 마커가 없는 경우(예: AI 에이전트가 이미 범위가 명확하고 직접 작성하기에 충분히 간단한 코드를 처리하는 경우), TDD를 건너뛰도록 선택할 수 있습니다. TDD를 건너뛰기로 선택하는 경우 .tdd-skipped 마커를 생성하여 /lfg 및 Ralph에게 TDD 게이트를 적용하지 말라고 신호를 보냅니다. 이 결정은 다음에 의해 결정되어야 합니다:
- 이 작업이 결정적 알고리즘 영역(예: 숫자 계산, 순수 함수, 또는 입력-출력 매핑이 테스트로부터 가장 큰 이점을 얻는 비즈니스 로직)입니까? → TDD 적용
- 이 작업이 비결정적 영역(예: UI 레이아웃, 데이터베이스 스키마, 또는 "작동"이 주관적인 시스템 통합)입니까? →
.tdd-skipped생성 - 이 작업이 I/O 무거운 영역(예: 네트워크 호출, 파일 시스템, 데이터베이스 쿼리)입니까? →
.tdd-skipped또는 매우 의도적인 테스트 전략을 가진 TDD 적용을 고려하세요 - 이 작업이 구성 및 배관 영역(예: 연결된 서비스, 구성 파일 로드, 미들웨어 체인)입니까? → TDD는 과도할 수 있으며
.tdd-skipped가 더 나은 경우가 많습니다
중요: TDD 마커를 변경하지 마세요. 이슈의 TDD 선언을 변경하지 마세요. .tdd-skipped를 생성하는 것은 이 실행에 대한 결정일 뿐이며 이슈 본문의 선언을 변경하지 않습니다.
TDD를 적용하기로 선택한 경우 → tdd 카드를 호출하세요(완전한 레드-그린-리팩터 루프를 실행하고 이 실행에 대해 .tdd-active를 생성). /tdd가 완료된 후 계속 진행하세요.
TDD를 건너뛰기로 선택한 경우 → .tdd-skipped 마커를 생성하고 직접 구축 단계로 진행하세요.
TDD 마커 생성기
TDD 적용 또는 건너뛰기를 선택한 후 분류 마커를 생성하세요:
# TDD 적용을 선택한 경우:
mkdir -p .claude && date -u +%Y-%m-%dT%H:%M:%SZ > .claude/.tdd-active
# TDD 건너뛰기를 선택한 경우:
mkdir -p .claude && date -u +%Y-%m-%dT%H:%M:%SZ > .claude/.tdd-skipped
이 마커는 /lfg가 읽어 Ralph에게 TDD 단계를 기다리지 말라고 알립니다. 마커는 단계 6에서 제거됩니다.
3. 구축
TDD를 적용하기로 결정한 경우 /tdd가 이 단계를 처리했으며 직접 구축할 코드가 거의 없습니다. TDD를 건너뛰기로 결정한 경우 직접 구축합니다.
TDD를 적용하거나 건너뛰는 결정이 이루어졌습니다. 이제 구현하세요.
- 계획의 윤곽을 따르세요. 가능한 한 계획의 변경 사항 목록을 따르도록 노력하세요. 한 번에 약간의 코드를 추가하고 각 추가 사항이 예상대로 작동하는지 빠르게 확인하세요.
- 각 변경 사항을 관련 코드베이스의 패턴 및 관례에 일치시키세요. 라이브러리, 프레임워크 및 패러다임을 일관되게 사용하세요.
- 올바른 위치에 변경 사항을 배치하세요. 예를 들어 올바른 디렉토리에 파일을 만들고 올바른 모듈에 코드를 추가합니다.
- 사이드 이펙트와 함께 변경하지 않는다는 계약을 존중하세요. 코드 영역을 추가하는 경우 기존 코드에 예기치 않은 사이드 이펙트를 도입하지 마세요.
- 가드가 제자리에 있는지 확인하세요. 입력 유효성 검사, 오류 처리, 데이터 무결성 검사.
- 변경 사항을 자체 문서화하도록 만드세요. 변수, 함수 및 클래스의 명확한 이름. 복잡한 논리를 설명하는 인라인 주석.
- 동시에 5개 이상의 파일을 편집하지 마세요. 변경 사항을 여러 개의 작은 청크로 나누고 각 청크를 테스트/검증하는 것을 고려하세요.
- 작업이 프론트엔드 구성 요소를 포함하는 경우: 접근성 속성(aria-*), 역할, 키보드 탐색, 포커스 관리 및 화면 판독기 텍스트를 포함하세요.
구축 단계에서 다음 경우 /lfg를 사용하세요:
.tdd-skipped가 존재하고 작업이 테스트가 의미 있는 영역인 경우, 구축 중인 각 단위에 대해/lfg게이트를 통과하세요./lfg는 무결성 검사 역할을 하며, 이는 이미 적용된 TDD를 대체하는 것입니다..tdd-active가 존재하는 경우/lfg는 선택 사항입니다 — TDD가 이미 레드-그린-리팩터를 통해 무결성을 보장했기 때문입니다. 그러나/lfg는 통합 또는 회귀 검사에 유용할 수 있습니다.- 작업이 복잡한 통합 또는 여러 서비스를 포함하는 경우, 최종적으로 작동하는 시스템을 구축하는 단계로서 구축 중
/lfg를 실행하세요.
4. 검증
실제 결과를 확인하세요. 계획 단계에서 정의한 대로 작업이 완료되었고 결과가 예상과 일치하는지 확인하세요.
- 빌드 확인:
npm run build(또는 프로젝트의 빌드 명령)가 변경 사항으로 성공하는지 확인하세요. 이는 구문 오류, 유형 오류 또는 기타 컴파일 타임 문제를 포착합니다. - Lint 및 포맷 확인:
npm run lint(또는 프로젝트의 린트/포맷 명령)가 통과하는지 확인하세요. - 테스트 실행:
.tdd-active가 있는 경우npm test(또는 프로젝트의 테스트 명령)가 통과하는지 확인하세요..tdd-skipped가 있는 경우 관련 유닛 또는 통합 테스트가 여전히 통과하는지 확인하세요. - 계획 검토: 단계 1의 계획을 다시 참조하세요. 모든 의도된 변경 사항이 이루어졌습니까? 범위 확장이 채택되었습니까, 아니면 추가 단계 7(README 업데이트)로 연기되었습니까?
- 변경 사항 검토:
git diff를 사용하여 변경된 각 파일이 예상과 일치하는지 확인하세요. git에서 모든 것이 깨끗해 보입니까? 실수로 변경된 파일이 있습니까? - 회귀 확인: 의도치 않게 기존 기능이 손상되었습니까? 작업이 광범위한 시스템에 영향을 미치는 경우 빠른 연기 테스트를 실행하는 것을 고려하세요.
- 문제 추적기에 작업 연결: 이슈 해결 방법을 문서화하세요.
검증 단계에서 /lfg 사용: 작업이 검증되었고 /lfg 게이트를 통과할 준비가 되었으면 실행하고 계속 진행하세요.
5. 읽음 표시
리서치 아티팩트가 존재하는 경우 읽음 표시. 이 실행이 Spike 이슈 또는 docs/solutions/의 솔루션 문서에서 생성된 리서치 아티팩트를 소비한 경우, 실행이 기록하기 위해 [_consumed_by_execute_] 텍스트를 리서치 아티팩트의 상단에 추가합니다.
이것은 리서치 아티팩트가 일회성 사용을 위해 설계되었기 때문에 수행됩니다: 여러 구현 실행이 동일한 아티팩트를 다시 읽는 대신, 하나의 구현 실행이 아티팩트를 읽고, 사용하고, 더 이상 관련이 없음을 표시합니다. 아티팩트가 이 실행보다 오래 지속되는 경우(예: 재사용 가능한 ADR 또는 아키텍처 결정), 읽음 표시를 하지 마십시오.
6. 정리
TDD 마커 제거:
rm -f .claude/.tdd-active .claude/.tdd-skipped
검토 노트 작성 (항상, 심지어 AFK 모드에서도). 다음 정보를 .claude/review-notes.md에 추가하세요:
# 리뷰 노트: <브랜치 이름>
## 요약
- **작업:** <이슈 번호 또는 작업 이름>
- **범위:** <단계 1의 계획에서 가져오기>
- **변경 사항 개요:** <변경된 파일 요약, 영향 영역>
- **TDD:** 적용됨 / 건너뜀 — 이유:
## 검토자 참고 사항
- <리뷰 중 특별한 주의가 필요한 사항>
- <미해결 질문 또는 열린 결정>
- <기존 계약과의 충돌 영역>
## 보안 / 규정 준수 확인
- <확인된 보안 영향 평가>
- <규정 준수 요구 사항이 확인되었거나 해당 없음>
- <비밀, 토큰 또는 자격 증명이 실수로 노출되지 않음 — 확인됨>
## 추가 메모
- <이 작업에서 배운 점, 주목할 만한 결정, 구현 중 발견된 놀라운 점>
AFK 검증이 필요한 장애물이 있는지 확인하세요. AFK 모드에서도 이 정리 단계는 적용됩니다. AFK 실행이 이 파일을 작성할 수 없는 방식으로 실패하는 경우(예: 디스크 공간 부족), 예외가 발생하고 스킬이 실패를 보고합니다.
7. 문서화 및 커밋
커밋 전에 step 6의 검토 노트가 있는지 확인하세요. 또한:
- README 및 문서: 작업이 공개 API, CLI 인터페이스, 구성 스키마 또는 프로젝트 문서를 변경하는 경우
README.md또는 관련 문서 파일을 업데이트하세요. 새 설정, 종속성 또는 아키텍처 변경 사항을 문서화하세요. - 차단됨 — 단계 0의 이슈 게이트가 차단을 반환한 경우
.claude/review-notes.md에 차단 상태를 문서화하고 진행하지 마십시오. - Changelog 항목: 프로젝트에
CHANGELOG.md가 있는 경우 적절한 섹션 아래에 항목을 추가하세요.
모든 변경 사항을 하나의 단일 커밋으로 커밋합니다. 하나의 구현 슬라이스, 하나의 커밋:
git add -A && git commit -m "<scope>: <message>
Closes #<이슈 번호> (해당하는 경우)
"
커밋 메시지 형식에 대한 프로젝트의 기존 규칙을 따르세요(conventional commits, 일대일 이슈-커밋 매핑 등). 적절한 범위 접두사(예: feat:, fix:, refactor:, docs: — 프로젝트가 따르는 모든 것)를 사용하세요.
푸시 금지 — 푸시 및 PR 생성은 /closeout이 처리합니다.
안전장치
| 조건 | 동작 |
|---|---|
| Lint/build/test가 실패함 | 수정하고 단계 3-5를 다시 실행 |
| 계획 범위 초과 | 범위 확장을 문서화하고, 범위를 초과한 통과된 변경 사항이 없는지 확인하고, 작업이 작동 가능한 상태인지 확인 |
| 브랜치가 오래됨(규칙 3) | 브랜치 전환/생성, 수정 사항 재적용 |
| 이슈가 차단됨(게이트) | 차단을 문서화하고, 사용자에게 알리고, 진행하지 않음 |
| 기본 브랜치(규칙 2) | 브랜치 생성 |
| EnterWorktree를 사용할 수 없음 | CD 접두사로 폴백 |
| 호스트 소유 격리(대기) | 대기, 제자리에서 작업, 워크트리 없음 |
| 호스트 소유 격리 + EnterWorktree 없음 | 호스트 시나리오에서는 적용되지 않음(워크트리가 생성되지 않음) |