pdca 프레임워크를 Codex에서 실전 사용 방법

pdca 프레임워크를 Codex에서 쓴다는 것은 작업을 느리게 만들기 위한 절차를 추가한다는 뜻이 아닙니다. 오히려 Codex가 빠르게 수정한 결과를 사람이 다시 추적하고 검증할 수 있도록 작업을 작은 주기로 묶는 방식입니다. Plan에서 기준을 정하고, Do에서 구현하고, Check에서 검증하고, Act에서 다음 기준으로 반영하는 흐름을 Codex CLI 프롬프트 안에서 반복하는 것이 핵심입니다.

이 글은 설치 설명보다 실전 사용 방법에 집중합니다. bkit과 pdca 스킬이 준비된 환경에서 Codex CLI에 `$pdca`를 어떻게 입력하고, 어떤 순서로 작업을 진행하며, 어떤 결과를 확인해야 하는지 설명합니다. 실행 예시는 모두 Codex CLI 기준으로 작성합니다.

실전 사용 전에 정해야 할 작업 단위

pdca 프레임워크를 Codex에서 쓸 때 가장 먼저 정해야 하는 것은 기능 이름입니다. 기능 이름이 없으면 계획 문서, 설계 문서, 분석 결과, 완료 보고서가 서로 연결되지 않습니다. 기능 이름은 짧고 구체적이어야 합니다.

예를 들어 글 생성기에서 researcher가 뽑은 키워드를 writer가 WordPress 태그로 반영하게 만드는 작업이라면 `keyword-tags-flow`처럼 정할 수 있습니다. 이미지 생성 흐름을 고치는 작업이라면 `image-maker-flow`가 더 적합합니다. 기능 이름은 파일명과 문서 경로에도 쓰이므로 공백보다 하이픈을 쓰는 편이 안전합니다.

feature: keyword-tags-flow
goal: researcher가 추출한 키워드를 writer draft의 tags에 반영한다
success: draft frontmatter에 3~7개 의미 있는 태그가 들어가고 테스트가 통과한다

이렇게 작업 단위를 정한 뒤 Codex CLI에서 `$pdca`를 실행합니다.

1단계: `$pdca status`로 현재 상태 확인

처음부터 plan을 만들기 전에 현재 프로젝트가 어떤 상태인지 확인해야 합니다. 이미 진행 중인 기능이 있을 수 있고, 이전 분석 결과가 남아 있을 수도 있습니다.

$pdca status

이 프롬프트를 Codex CLI에 입력하면 Codex는 PDCA 상태 파일과 관련 문서를 확인해야 합니다. 상태 파일이 있다면 현재 phase, 진행률, 다음 권장 단계를 보여 줍니다. 상태 파일이 없다면 새 기능을 plan 단계부터 시작하라고 안내할 수 있습니다.

좋은 상태 확인 결과는 단순히 “정상”이라고 말하지 않습니다. 어떤 기능이 어느 단계에 있고, 다음에 어떤 명령을 실행해야 하는지까지 보여 줘야 합니다.

PDCA Status
Feature: keyword-tags-flow
Phase: plan
Next: $pdca design keyword-tags-flow

2단계: `$pdca plan`으로 성공 기준 만들기

계획 단계에서는 구현 방법보다 성공 기준이 먼저입니다. Codex가 파일을 고치기 전에 무엇이 바뀌어야 하는지, 어떤 범위는 건드리지 말아야 하는지, 검증은 무엇으로 할지 정해야 합니다.

$pdca plan keyword-tags-flow

이 요청을 받은 Codex는 계획 문서를 만들거나 기존 계획을 갱신합니다. 계획에는 다음 내용이 들어가야 합니다.

• 목표: researcher 키워드를 writer 태그에 반영한다.
• 범위: `agent_pipeline.py`, writer draft frontmatter, 관련 테스트를 포함한다.
• 제외 범위: WordPress 게시글의 기존 공개 상태는 바꾸지 않는다.
• 성공 기준: `tags:`에 primary keyword와 추출 키워드가 들어간다.
• 검증: 관련 단위 테스트와 전체 로컬 검증을 통과한다.

계획 단계에서 흔히 하는 실수는 “코드를 고친다”를 목표로 쓰는 것입니다. 코드는 수단입니다. 목표는 사용자가 관찰할 수 있는 변화여야 합니다. 이 경우에는 “생성된 글에 키워드 태그가 붙는다”가 목표입니다.

3단계: `$pdca design`으로 변경 위치를 정하기

설계 단계에서는 어떤 파일을 왜 바꾸는지 정리합니다. Codex는 이 단계에서 바로 구현하지 말고, 데이터 흐름과 검증 지점을 먼저 분리해야 합니다.

$pdca design keyword-tags-flow

예를 들어 writer 태그 반영 작업의 설계는 다음처럼 잡을 수 있습니다.

Input:
- output/<topic>/research.md
- data/topics.csv keyword
- draft frontmatter

Flow:
- researcher가 Extracted Keywords를 만든다.
- writer 단계가 research.md를 읽는다.
- primary keyword를 첫 번째 tag로 둔다.
- 중복을 제거하고 3~7개 태그를 만든다.
- draft.md frontmatter의 tags를 갱신한다.

Verification:
- 한글 키워드가 추출되는지 테스트한다.
- frontmatter tags가 교체되는지 테스트한다.
- 전체 로컬 검증을 실행한다.

설계가 있으면 Codex가 임의로 본문에 해시태그를 덧붙이거나, 키워드를 문장마다 반복하는 식의 나쁜 SEO 보강으로 흐를 가능성이 줄어듭니다. 태그는 frontmatter에 들어가야 하고, 본문에는 자연스럽게 들어가야 한다는 기준이 생기기 때문입니다.

4단계: `$pdca do` 또는 직접 구현 지시

Do 단계에서는 실제 구현을 진행합니다. Codex CLI에서는 다음처럼 지시할 수 있습니다.

$pdca do keyword-tags-flow

또는 더 직접적으로 말할 수 있습니다.

$pdca do keyword-tags-flow
research.md의 Extracted Keywords를 writer draft frontmatter tags에 반영해라.
primary keyword를 첫 번째 태그로 두고, 중복을 제거하고, 3~7개만 남겨라.

이때 Codex가 해야 할 일은 파일을 많이 바꾸는 것이 아닙니다. 설계에서 정한 변경 지점만 고쳐야 합니다. 예를 들어 `agent_pipeline.py`에 키워드 추출 함수와 frontmatter tags 갱신 함수를 추가하고, 테스트 파일에 회귀 테스트를 넣는 정도가 적절합니다.

구현 예시는 다음과 같은 형태가 될 수 있습니다.

def extract_research_keywords(research_text: str) -> list[str]:
    section = find_markdown_section(research_text, "Extracted Keywords")
    return [item.strip("- ").strip() for item in section.splitlines() if item.strip()]

def ensure_writer_keyword_tags(draft_text: str, primary_keyword: str, keywords: list[str]) -> str:
    tags = dedupe([primary_keyword, *keywords])[:7]
    return replace_frontmatter_list(draft_text, "tags", tags)

실제 코드가 이 예시와 똑같을 필요는 없습니다. 중요한 것은 입력, 처리, 출력이 설계와 맞아야 한다는 점입니다.

5단계: `$pdca analyze`로 설계와 결과 비교

구현이 끝났다고 바로 완료하면 안 됩니다. Check 단계에서는 설계와 실제 결과가 맞는지 비교해야 합니다.

$pdca analyze keyword-tags-flow

분석 단계에서 Codex는 계획과 설계를 읽고, 실제 코드와 테스트를 비교합니다. 예를 들어 설계에는 “한글 키워드 추출”이 있었는데 테스트가 영어 키워드만 확인한다면 gap입니다. 설계에는 “3~7개 태그”가 있었는데 코드가 모든 키워드를 무제한으로 넣는다면 이것도 gap입니다.

분석 결과는 다음처럼 나와야 합니다.

Match:
- research.md의 Extracted Keywords를 읽는다.
- primary keyword를 첫 번째 tag로 둔다.
- 중복 제거가 있다.

Gap:
- 한글 키워드 회귀 테스트가 부족하다.
- 전체 로컬 검증 결과가 아직 없다.

Match Rate: 80%
Next: $pdca iterate keyword-tags-flow

이 단계는 Codex가 스스로 “다 됐다”고 말하는 것을 막는 장치입니다. 결과가 계획과 맞는지 증거로 확인해야 합니다.

6단계: `$pdca iterate`로 부족한 부분 고치기

분석 결과 match rate가 낮거나 gap이 남아 있다면 iterate를 실행합니다.

$pdca iterate keyword-tags-flow

iterate 단계에서는 새 기능을 추가하기보다 분석에서 나온 gap을 먼저 고칩니다. 예를 들어 한글 키워드 테스트가 부족하다면 테스트를 추가합니다. 전체 검증을 실행하지 않았다면 실행합니다. 코드가 태그 수를 제한하지 않는다면 제한을 추가합니다.

이 단계에서 중요한 것은 범위 통제입니다. gap과 관계없는 리팩터링을 시작하면 PDCA 루프가 흐려집니다. Act 단계는 “부족한 것을 보완하는 단계”이지 “마음에 안 드는 코드를 전부 고치는 단계”가 아닙니다.

7단계: `$pdca report`로 완료 기록 남기기

검증이 끝나면 report 단계로 마무리합니다.

$pdca report keyword-tags-flow

완료 보고서에는 어떤 요구를 처리했는지, 어떤 파일을 바꿨는지, 어떤 테스트를 통과했는지, 남은 위험이 무엇인지 들어가야 합니다. 단순히 “완료”라고 적으면 다음 작업자가 같은 판단을 반복해야 합니다.

좋은 보고서는 다음 정보를 포함합니다.

• 변경 요약: writer 단계에서 research keyword를 tags에 반영했다.
• 검증: `python -m unittest discover -s tests` 통과.
• 운영 반영: 원격 배포 완료.
• 남은 위험: 실제 새 글 생성 시 태그가 너무 일반적이면 운영자가 keyword를 보정해야 한다.
• 다음 기준: 새 writer 정책 변경 시 태그 회귀 테스트를 함께 갱신한다.

실제 Codex CLI 프롬프트 묶음

아래는 하나의 기능을 끝까지 진행하는 Codex CLI 실행 명령 묶음입니다. 여기서 실행 명령은 터미널 명령이 아니라 Codex CLI에 입력하는 프롬프트 명령을 뜻합니다.

$pdca status

$pdca plan keyword-tags-flow
글 생성기에서 researcher가 추출한 키워드를 writer draft의 WordPress tags에 반영하는 작업이다.
성공 기준은 draft frontmatter에 primary keyword와 추출 키워드가 3~7개 들어가고, 한글 키워드 테스트와 전체 검증이 통과하는 것이다.

$pdca design keyword-tags-flow
research.md의 Extracted Keywords, data/topics.csv의 keyword, draft frontmatter tags 사이의 데이터 흐름을 설계하라.
본문에 키워드를 억지 반복하지 말고 tags와 자연스러운 제목/도입/H2/결론 반영으로 처리하라.

$pdca do keyword-tags-flow
설계에 따라 구현하고 관련 테스트를 추가하라.
작업 후 python -m unittest discover -s tests와 로컬 통합 검증을 실행하라.

$pdca analyze keyword-tags-flow
설계와 구현 결과를 비교하고 gap이 있으면 목록으로 보여라.

$pdca iterate keyword-tags-flow
분석에서 나온 gap만 우선 수정하고 다시 검증하라.

$pdca report keyword-tags-flow
완료 범위, 변경 파일, 검증 결과, 남은 위험을 보고서로 정리하라.

이 묶음을 그대로 외울 필요는 없습니다. 중요한 것은 작업이 plan 없이 do로 바로 들어가지 않고, do 이후에는 analyze와 iterate를 거친다는 점입니다.

필요하다면 이 프롬프트 묶음을 팀 내부 스크립트 문서에 저장해 반복 작업의 표준 입력으로 사용할 수 있습니다. 다만 스크립트처럼 재사용하더라도 기능 이름과 성공 기준은 매번 현재 작업에 맞게 바꿔야 합니다.

실전에서 자주 실패하는 지점

첫 번째 실패는 `$pdca plan`을 형식적으로만 실행하는 것입니다. 계획이 “기능을 개선한다”처럼 추상적이면 Codex는 무엇을 통과 기준으로 삼아야 할지 알 수 없습니다. 계획에는 반드시 관찰 가능한 성공 기준이 있어야 합니다.

두 번째 실패는 Check 단계를 생략하는 것입니다. 테스트를 돌리지 않았거나, 실제 UI나 공개 페이지를 확인하지 않았는데 완료라고 판단하면 나중에 운영 화면에서 문제가 드러납니다. Codex 작업에서는 로컬 테스트와 실제 실행 환경 검증을 분리해서 봐야 합니다.

세 번째 실패는 Act 단계에서 범위를 넓히는 것입니다. 분석 결과는 키워드 태그 문제였는데 갑자기 UI 전체를 고치거나 배포 구조를 바꾸면 원래 목표가 흐려집니다. iterate는 gap을 줄이는 단계로 제한해야 합니다.

적용 후 점검 기준

pdca 프레임워크를 Codex에서 제대로 사용했는지는 다음 질문으로 확인할 수 있습니다.

• 기능 이름이 명확한가?
• Plan에 성공 기준과 제외 범위가 있는가?
• Design에 입력, 처리, 출력, 검증이 연결되어 있는가?
• Do에서 설계 범위를 벗어난 변경을 하지 않았는가?
• Analyze가 실제 코드와 테스트를 비교했는가?
• Iterate가 gap만 고쳤는가?
• Report에 검증 결과와 남은 위험이 남았는가?

이 질문에 답할 수 있으면 Codex의 작업은 단순 대화가 아니라 반복 가능한 실전 프로세스가 됩니다.

결론

pdca 프레임워크를 Codex에서 실전 사용하려면 `$pdca`를 단순한 명령 접두어로 보면 안 됩니다. `$pdca plan`은 성공 기준을 만들고, `$pdca design`은 변경 위치를 정하고, `$pdca do`는 구현을 진행하고, `$pdca analyze`는 설계와 결과를 비교하며, `$pdca iterate`는 부족한 부분을 고치고, `$pdca report`는 완료 기록을 남깁니다.

Codex CLI에서 이 흐름을 지키면 AI가 빠르게 움직이는 장점은 유지하면서도 작업의 근거와 검증 결과를 남길 수 있습니다. 결국 pdca 프레임워크의 실전 가치는 문서를 많이 만드는 데 있지 않습니다. 같은 실수를 줄이고, 다음 작업자가 같은 기준으로 이어서 일할 수 있게 만드는 데 있습니다.

더 확인할 자료

아래 링크는 이 글의 기준과 배경을 확인할 수 있는 공식 자료입니다.

• bkit.ai
• github.com/popup-studio-ai/bkit-claude-code
• openai.com/ko-KR/index/harness-engineering