PDLC 구축에 대한 회고 — 나의 Claude Code 워크플로우가 실제로 기능을 완성하도록 강제하는 31개의 슬래시 명령어(slash commands). Claude Code와 6개월간 페어 프로그래밍(pair-programming)을 하며 한 가지 불편한 진실을 배웠습니다. AI는 코드를 작성하는 데는 뛰어나지만, 소프트웨어 생명 주기(software lifecycle)의 나머지 부분에는 형편없다는 사실입니다. AI는 오직 채팅 기록만이 PRD(제품 요구 사항 문서)의 존재를 증명할 뿐인데도 즐겁게 "완료"라고 말합니다. 테스트를 작성하긴 하지만 구현이 끝난 후에 작성하므로, "TDD(테스트 주도 개발)"를 정중한 거짓말로 만듭니다. 새로운 세션을 시작하는 순간 어떤 기능이 어느 단계에 있는지 놓쳐버립니다. 아무런 결과도 내지 못하는 린트 수정(lint-fix) 루프에 빠지기도 합니다. 이 중 어느 것도 모델의 잘못이 아닙니다. 모델은 당신이 요청하는 순간에 당신이 요청한 대로 행동할 뿐입니다. 문제는 "먼저 PRD를 작성해 주세요", "먼저 실패하는 테스트를 작성해 주세요"와 같은 느슨한 관습(soft conventions)이 스스로 작업 기억(working memory)을 유지하는 인간에게 대화하는 방식이라는 점입니다. LLM은 그렇지 않습니다. LLM에게는 모델이 기억해야 하는 규칙이 아니라, 워크플로우 자체가 강제하는 규칙인 엄격한 계약(hard contracts)이 필요합니다. 이것은 제가 그 확신을 PDLC(Product Development Life Cycle)라는 이름의 Claude Code 플러그인으로 어떻게 인코딩했는지, 그리고 그 과정에서 무엇이 저를 놀라게 했는지에 대한 이야기입니다.

계약의 형태
PDLC는 세 가지 계층으로 구성된 31개의 슬래시 명령어(slash commands)를 제공합니다:

• 진입점(Entry points) (3개): /pdlc-feature, /pdlc-fix, /pdlc-status — 한 문장이 전체 체인을 구동합니다.
• 단계(Stages) (11개): /pdlc-prd, /pdlc-design, /pdlc-tdd, /pdlc-implement, /pdlc-review, /pdlc-e2e, /pdlc-ship, ... — 세밀한 제어가 필요할 때 사용합니다.
• 도구(Tools) (17개): /pdlc-ui-design, /pdlc-db-migrate, /pdlc-security, /pdlc-perf, ... — 특화된 관심사들을 다룹니다.

모든 계층
산출물(artifacts)을 생성하는 모든 1/2 단계는 제가 '철칙(Iron Law)'이라 부르는 다섯 가지 불변량(invariants)에 묶여 있습니다:

1. 디스크에 저장(Persist to disk). 모든 산출물(PRD, API 설계, DB 스키마, 테스트 계획, 리뷰 노트)은 docs/ 아래의 실제 파일로 저장됩니다. AI가 무엇을 했는지 git diff로 확인할 수 있습니다.
2. 상태 머신(state machine) 업데이트. 각 단계는 docs/.pdlc-state/<feature-id>.json을 작성합니다. 새로운 세션을 시작하더라도 /pdlc-status가 모든 기능의 정확한 상태를 알려줍니다.
3. 테스트 우선(Tests first).

저는 /pdlc-tdd가 해당 기능에 대해 실패 테스트 아티팩트를 디스크에 생성하지 않았다면, /pdlc-implement는 진행을 거부합니다. 실질적인 TDD 빨간불 게이트(red-light gate)입니다. 자체 점검(Self-check). 모든 단계는 인계되기 전에 자체 감사(self-audit)를 실행합니다. 검토 과정에서 세 단계 떨어진 곳에서 드리프트(drift)를 포착하는 것이 아니라, 단계 경계(stage boundary)에서 포착합니다. 일회성 복구(One-shot repair). 자동 수정 루프는 최대 한 번만 실행됩니다. 만약 특정 단계의 출력이 자체 감사를 통과하지 못하면, 모델은 이를 복구할 기회를 한 번 얻고, 그 후 인간에게 문제를 플래그 지정합니다. 토큰 예산이 고갈될 때까지 '수정 → 확인 → 수정 → 확인 → 수정'하는 일은 더 이상 없습니다.

무엇이 저를 놀라게 했는지 1. 상태 머신(state machine)이 예상보다 훨씬 중요했습니다. 저는 처음에는 지속성 규칙(persistence rule)만으로 시작했습니다. 모든 것을 디스크에 기록하는 것이었죠. 그것도 도움이 되었지만, 사용한 지 일주일 만에 AI에게

이 방식이 한계에 부딪히는 지점

솔직하게 밝혀야 할 세 가지가 있습니다:

1. Claude Code 전용입니다. 저는 슬래시 명령어 (slash commands)와 스킬 (skills)을 일급 기본 요소 (first-class primitives)로 사용합니다. Cline이나 Cursor에는 이에 직접적으로 대응하는 기능이 없습니다. 이식은 가능하지만 (계약이 bash + markdown으로 되어 있음), 비용이 들지 않는 것은 아닙니다.

2. 철칙 (Iron Law)은 법이 아닙니다. 결심한 사용자라면 상태 파일 (state file)을 수동으로 편집하거나, /pdlc-tdd를 거치지 않고 /pdlc-implement를 직접 호출할 수 있습니다. 계약은 가드레일 (guardrails)이지, 감옥 (jail)이 아닙니다. 이는 의도된 설계입니다. 추가 명령어 하나로 넘어갈 수 있는 가드레일이 대개 적절한 법입니다.

3. 사소한 변경에 대한 오버헤드 (Overhead). 단 3줄의 CSS 수정을 위해 전체 체인을 실행하는 것은 과합니다. 이를 위해 /pdlc-fix (더 가벼운 체인)가 존재하지만, "기능 (feature)"와 "수정 (fix)" 사이의 경계는 주관적입니다.

언제 사용해야 하는가

AI 에이전트와의 워크플로우가 다음과 같다면:

• 기능 하나당 여러 세션이 필요함 → 상태 머신 (state machine)의 가치가 충분함
• 나중에 git diff로 확인하고 싶은 내용이 있음 → 영속성 (persistence)의 가치가 충분함
• 테스트가 없어서 후회했던 코드를 작성함 → TDD의 red light가 가치가 충분함

만약 일회성 스크립트, 리팩토링 작업, 또는 단일 세션 프로토타입을 위해 AI를 사용한다면, PDLC는 작업에 비해 절차가 너무 복잡합니다. 규율을 지킬 가치가 있는 곳에 사용하세요.

직접 시도해보기

설치 (clone 불필요):
curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh | bash -s -- --global

그 다음 Claude Code에서:
/pdlc-feature add phone-number verification to user login

그러면 기능 ID (feature ID)를 할당하고, 체인을 따라 진행하며, 중요한 단계를 건너뛰는 것을 거부할 것입니다.

저장소 (MIT): https://github.com/kanfu-panda/pdlc-skills

이것을 기반으로 무언가를 만드셨다면 Discussion을 남겨주세요. 제가 테스트하지 못한 어떤 형태들이 견고하게 유지되는지 꼭 보고 싶습니다.

— kanfu-panda