기본 시작점으로서의 Claude Code 플랜 모드

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

무엇이 달라지는가

시작하기

• 전제 조건: 의도 아티팩트(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를 업데이트합니다. 둘 사이의 동기화를 강제하기 위해 훅을 사용하는 것을 고려하세요.

실제 모습

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

plan.md:

# 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가 파일을 편집할 수 없기 때문에 이를 자체적으로 강제합니다. 계획과 그 수정 내역은 누가 승인했는지와 함께 기록됩니다. 일상적인 변경은 엔지니어가 승인하며, 조직이 더 높은 위험으로 분류하는 사항은 테크 리드나 아키텍트에게 전달됩니다.

측정 방법

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

오토 모드의 Claude Code

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

이제 변화의 방향은 사용자가 에이전트의 편집을 지켜보고 작업을 검토하는 것에서, 더 긴 자율 세션 이후 아티팩트를 검토하는 것으로 옮겨갑니다. 오토 모드는 워크트리와 함께 사용할 때 개인과 팀 전체에 걸친 병렬 작업을 더욱 가능하게 하며, 6단계: 유지보수에서 설명한 대로 SDLC를 자율적으로 실행하고 루프를 닫는 데 근본적인 역할을 합니다.

레거시 시스템과 단일 진실 공급원

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

아래 구성을 설정하여 아티팩트별로 다른 선택을 하면서도 하나의 단일 진실 공급원을 가질 수 있습니다:

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

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