로드 중

기본 출발점으로서의 Claude Code 플랜 모드

강의 46분

엔지니어는 플랜 모드로 Claude Code 세션을 시작하고, 2단계: 설계에서 승인된 spec.md를 Claude에게 제공한 다음, Claude가 질문하도록 하여 만족할 때까지 계획을 반복적으로 수정합니다.

변경되는 사항

기존 방식AI 네이티브 방식
엔지니어가 설계를 읽고 코드 작성을 시작합니다. 변경 사항을 어떻게 구현할지, 어떤 파일과 어떤 테스트를 사용할지는 엔지니어의 머릿속에만 있거나 기껏해야 티켓 댓글에 남아 있을 뿐입니다. 다른 누구도 이를 검토할 수 없습니다. 검토자가 처음 보게 되는 것은 완성된 diff이며, 그 시점에는 재작업이 느려집니다.작업은 Claude가 플랜 모드에서 작성한 문서화된 계획으로 시작되며, 이 모드에서 Claude는 아무것도 변경하지 않고 코드베이스를 읽을 수 있습니다. 엔지니어는 코드가 작성되기 전에 계획을 수정하며, 승인된 버전은 이후 단계에서 대조 확인할 수 있도록 plan.md로 커밋됩니다.

시작하기

  • 전제 조건: 존재하는 경우 의도(intent) 아티팩트(intent.md 또는 spec.md)가 있으면 도움이 되며, CLAUDE.md 파일도 도움이 됩니다.
  • 인프라: 저장소에 접근할 수 있는 Claude Code.

실행 방법

  1. 엔지니어는 Claude와 함께 플랜 모드로 세션을 시작합니다.
  2. 엔지니어는 Claude에게 intent.md와 spec.md를 제공하고, 변경될 파일, 작업 순서, 이를 증명할 테스트를 명시한 구현 계획을 요청합니다.
  3. 변경 사항이 무엇을 손상시킬 수 있는지, 어떤 단계가 가장 위험한지, Claude가 선택하지 않은 다른 옵션은 무엇인지 질문하여 계획을 면밀히 검토합니다.
  4. 해당 대화를 본 적이 없는 엔지니어도 계획만으로 변경 사항을 구현할 수 있을 때까지 반복합니다.
  5. 승인된 계획을 plan.md로 커밋합니다. 이 계획은 감사 추적에 포함되며, PR 검토 플레이(5단계: 배포)는 최종 diff를 이 계획과 대조하여 확인합니다.
  6. 계획을 승인하고 Claude가 구현하도록 합니다. 탄탄한 계획이 있으면 구현은 대개 한 번에 끝납니다.
  7. 구현이 계획에서 벗어나는 경우, 동일한 커밋에서 plan.md를 업데이트합니다. 둘 사이의 동기화를 강제하기 위해 훅(hook) 사용을 고려하세요.

실제 모습

아래 계획은 한 보험사에서 이루어진 변경 사항에 대한 것입니다: 고객 포털 내의 패널로, 청구 상태를 표시합니다. 이 패널은 포털의 백엔드인 claims-api를 호출하며, claims-api는 오래된 내부 시스템인 claims-core에서 데이터를 읽어옵니다.

plan.md:

markdown
# Plan: claims status self-service (from intent.md and spec.md)

## Files that change

portal/src/claims/StatusPanel.tsx (new), claims-api/routes/status.py, claims-api/tests/test_status.py

## Order of work

1. Add the status endpoint behind existing auth (R1, R2, R3).
2. Panel against the endpoint, with the 60-second cache (R1, R4).
3. Wire into the portal nav.

## Risks

The claims-core API rate-limits at 50 rps; the panel must cache (spec concern 3).

## Proof

test_status.py covers the four claim states (R2) and fails on any extra field (R3); screenshot matches the approved mock.

R1부터 R4까지는 spec.md에 번호가 매겨진 요구 사항이며, concern 3은 spec.md에서 표시한 위험입니다. 계획이 이를 인용하고 있으므로, 검토자는 계획을 스펙과 한 줄씩 대조하여 확인할 수 있습니다.

거버넌스 고려 사항

설계 검토는 코드가 생성되기 전에 이루어지며, 이 시점에는 방향을 바꾸는 것이 여전히 문서를 편집하는 문제에 불과합니다. 플랜 모드는 엔지니어가 계획을 승인할 때까지 Claude가 파일을 편집할 수 없기 때문에 이를 자체적으로 강제합니다. 계획과 그 수정 사항은 누가 승인했는지와 함께 기록됩니다. 일상적인 변경 사항은 엔지니어가 승인하며, 조직이 더 높은 위험으로 분류하는 사항은 테크 리드(tech lead)나 아키텍트에게 전달됩니다.

측정 방법

  • 선행 지표: 첫 번째 구현 단계에서 머지되는 변경 사항의 비율, 그리고 PR 메타데이터 내 필요한 데이터를 포함하여 계획 승인부터 PR 머지까지 걸리는 시간.
  • 후행 지표: 변경 사항당 재작업 주기(마찬가지로 PR 메타데이터 기준), 그리고 머지된 diff가 커밋된 plan.md와 여전히 일치하는 빈도.

오토 모드(auto mode)의 Claude Code

Claude Code는 오토 모드로도 실행할 수 있습니다. 이 모드에서는 엔지니어가 계획을 반복적으로 수정하고 승인하며, 이후 Claude는 수정 건마다 묻지 않고 각 변경 사항을 적용합니다. 이후 플레이의 가드레일이 성숙해짐에 따라(잘 조정된 CLAUDE.md, 정책을 인코딩한 Skills, 안전하지 않은 작업을 차단하는 훅, Claude가 실행할 수 있는 테스트 스위트 등), 오토 모드는 일상적인 작업, 즉 엄격한 spec.md, 작은 영향 범위, 그리고 테스트가 이미 커버하는 코드의 경우 기본값이 됩니다.

이러한 변화는 사용자가 에이전트의 편집 작업을 지켜보고 그 동작을 검토하는 방식에서 벗어나, 더 긴 자율 세션 이후 아티팩트를 검토하는 방식으로 옮겨가는 것을 의미합니다. 오토 모드는 워크트리(worktree)와 함께 사용할 경우 개인과 팀 전반에 걸친 병렬 작업을 더욱 가능하게 하며, 6단계: 유지 관리에서 설명한 대로 SDLC를 자율적으로 실행하고 루프를 완결하는 데 근본적인 역할을 합니다.

레거시 시스템과 단일 진실 공급원(source of truth)

기존 SDLC 프로세스는 Markdown 파일이 아닐 뿐, 이미 아티팩트를 추적하고 있을 가능성이 높습니다. 작업 항목은 Jira에 있을 수 있고, 요구 사항은 규제 추적성이 내장된 도구에, 설계는 Figma에, 변경 승인은 변경 관리 위원회(change board)에 있을 수 있습니다. 이러한 시스템은 감사자와 규제 기관이 이미 이를 수용하고 있고 다른 팀들이 이에 의존하고 있기 때문에 대체하기 어려우며, 따라서 AI 네이티브 SDLC는 기존에 존재하는 것에 맞춰 구성되어야 합니다. 프로세스가 생성하는 각 아티팩트마다 하나의 시스템을 단일 진실 공급원(source of truth)으로 지정해야 하며, 다른 시스템은 사본이나 링크를 보유해야 합니다.

아티팩트별로 선택이 달라지는, 단일 진실 공급원을 갖추기 위한 아래의 구성을 설정할 수 있습니다:

  • 저장소를 단일 진실 공급원으로 사용. Markdown 아티팩트가 권위 있는 기록이며, 레거시 시스템은 커밋 내의 파일을 참조합니다. 모든 기록이 하나의 도구에 존재하고 하나의 타임스탬프 권한을 가지므로, 엔지니어링 주도 조직에게는 가장 깔끔한 구성 중 하나가 될 수 있습니다.
  • 레거시 시스템이 진실 공급원인 경우. Jira, ServiceNow, 또는 요구 사항 도구가 권위 있는 기록을 보유하며, Markdown 아티팩트는 작업용 사본입니다. Claude는 세션 시작 시 해당 기록을 읽어오고, 스펙이나 계획을 생성한 동일한 세션 내에서 Model Context Protocol(MCP) 커넥터를 통해 결과를 다시 기록합니다.
  • 연결(linkage)을 최소 기준으로 설정. 모든 아티팩트에는 기록 ID가 기재되며, 모든 레거시 기록에는 Markdown 파일의 커밋 SHA가 포함됩니다. 두 개의 진실 공급원이 존재하는 만큼, AI 네이티브 SDLC로 전환할 때 연결(linkage) 옵션이 시작하기에 좋은 지점입니다.

레거시 시스템과 AI 네이티브 Markdown 우선 시스템은 둘 사이에 연결이 있거나 둘 중 하나가 단일 진실 공급원으로 선언되는 한 공존할 수 있습니다.