Codex와 bkit으로 PDCA를 실제 적용하는 방법

조회 185좋아요 0

이 글의 목적은 PDCA 개념을 설명하는 것이 아닙니다. Codex를 사용해 실제 기능을 고치고, 그 과정에서 bkit의 PDCA 방식이 어떻게 작업 품질을 잡아 주는지 하나의 사례로 보여주는 것입니다.

소개

bkit은 AI 네이티브 개발을 PDCA 방법론으로 운영하도록 돕는 Vibecoding Kit입니다. bkit 사이트는 이를 “AI-native development powered by PDCA methodology”로 설명하고, 9단계 파이프라인과 전문 에이전트, 품질 게이트를 통해 AI 코딩 흐름을 체계화한다고 소개합니다.

이번 사례의 작업 대상은 블로그 작성 도구였습니다. 사용자는 글 생성기에서 본문 이미지를 다루는 방식이 기대와 다르다고 지적했습니다. 처음에는 이미지 URL이 텍스트처럼 보였고, 이미지 위치도 의도와 달랐으며, AI 생성 이미지와 직접 업로드 이미지를 선택하는 흐름도 부족했습니다. 이 문제를 Codex로 수정하면서 bkit의 PDCA 사고방식을 적용했습니다.

1. bkit을 쓰는 이유

AI 코딩 에이전트는 빠르게 코드를 제안합니다. 문제는 그 코드가 실제 요구사항을 만족하는지, 기존 설계와 맞는지, 배포 후에도 의도대로 보이는지 확인하는 일입니다. bkit은 이 지점을 PDCA 흐름으로 관리합니다.

bkit의 공개 설명을 기준으로 보면 핵심은 세 가지입니다.

bkit 관점	의미	Codex 작업에서의 효과
PDCA	Plan, Do, Check, Act로 작업을 나눔	요청을 구현 전 검증 기준으로 바꿈
품질 게이트	설계와 구현의 차이, 테스트, 보안 등을 확인	“동작하는 것처럼 보이는 코드”를 줄임
문서 주도 흐름	계획, 설계, 분석, 보고를 남김	다음 작업에서 같은 실수를 반복하지 않음

따라서 bkit은 “AI가 코드를 잘 짜게 하는 마법”이라기보다, AI가 만든 결과를 계속 확인하고 보정하게 만드는 작업 하네스에 가깝습니다.

2. 사례 목표: 블로그 작성 도구 이미지 흐름 개선

이번 사례의 실제 요구사항은 다음과 같았습니다.

본문 이미지는 URL 문자열이 아니라 이미지로 보여야 한다.
이미지는 소개글 아래에 배치되어야 한다.
이미지 크기는 본문 너비에 맞아야 한다.
AI 생성 이미지와 로컬 이미지 업로드를 선택할 수 있어야 한다.
로컬 이미지를 선택할 때는 파일 탐색기와 업로드 컴포넌트가 필요하다.
이미지 생성 뒤 불필요한 설명 문구나 캡션을 붙이지 않아야 한다.
발행된 글에도 변경 결과가 실제로 반영되어야 한다.

이 요구사항은 단순히 버튼 하나를 추가하는 작업이 아니었습니다. 글 생성기 UI, 이미지 업로드 API, WordPress 미디어 업로드, 초안 Markdown, 발행 글 동기화, 공개 페이지 검증까지 연결된 작업이었습니다. 그래서 Codex에게 바로 “고쳐줘”라고 맡기기보다 bkit식 PDCA로 작업을 나눠야 했습니다.

3. Plan: 요구사항을 검증 가능한 작업으로 바꾼다

Plan 단계에서 가장 먼저 한 일은 사용자의 말을 실행 가능한 체크 항목으로 바꾸는 것이었습니다.

사용자 요구	Plan 단계에서 바꾼 작업 정의
이미지 URL이 아니라 이미지로 보여야 한다	Markdown 이미지를 WordPress `<figure><img>` HTML로 변환하고 공개 글에서 확인
소개글 밑에 위치해야 한다	초안의 소개 섹션 다음 위치에 이미지 삽입
본문 너비에 맞춰라	이미지 HTML에 `width:100%`, `height:auto` 스타일 적용
AI 생성과 업로드를 선택하게 하라	글 생성기 UI에 이미지 액션 모드와 업로드 컴포넌트 추가
로컬 파일 탐색기가 필요하다	`<input type="file">`, 파일 선택 버튼, 드래그앤드롭, 미리보기 구현
불필요한 설명 태그를 붙이지 마라	이미지 아래 설명 문구와 캡션 없음 검증

bkit을 활용할 때 중요한 지점은 이 변환입니다. “원하는 느낌”을 “검증 가능한 조건”으로 바꿔야 Check 단계가 작동합니다. 이 과정을 건너뛰면 Codex가 코드를 만들어도 성공 여부를 판단하기 어렵습니다.

4. Do: Codex로 기능을 구현한다

Do 단계에서는 Codex가 실제 코드와 콘텐츠를 수정했습니다. 작업은 크게 네 부분으로 나뉘었습니다.

첫째, 글 생성기 UI에 이미지 모드를 추가했습니다. 사용자가 AI 생성과 이미지 업로드를 선택할 수 있게 하고, 업로드 선택 시 로컬 파일 탐색 버튼과 업로드 버튼이 보이도록 구성했습니다.

둘째, 업로드 컴포넌트를 만들었습니다. 파일 선택, 드래그앤드롭, 선택 이미지 미리보기, PNG/JPG/WEBP 제한, WordPress 미디어 업로드 호출을 한 흐름으로 묶었습니다.

셋째, 본문 이미지 처리 규칙을 정리했습니다. 이미지는 초안 본문에 Markdown 이미지로 들어가되, WordPress 전송 시 실제 이미지 태그로 렌더링되도록 했습니다. 또한 이미지 위치는 소개글 아래로 고정했습니다.

넷째, 발행된 글을 다시 동기화했습니다. 이미 발행된 `ai-008` 글은 초안만 바꿔서는 공개 페이지가 바뀌지 않습니다. 그래서 WordPress post ID `645`의 내용을 새 초안 기준으로 다시 업데이트했습니다.

이 단계에서 Codex의 장점은 여러 파일과 서버 작업을 이어서 처리할 수 있다는 점입니다. 다만 그 작업이 안전하려면 Plan 단계에서 정한 경계가 필요합니다.

5. Check: 테스트와 운영 검증으로 확인한다

Check 단계에서는 “코드가 저장됐다”가 아니라 “요구사항이 실제로 충족됐다”를 확인했습니다.

수행한 검증은 다음과 같습니다.

검증 항목	확인 방법	결과
UI 문자열 반영	배포된 배포된 HTML 확인	이미지 업로드, WordPress 미디어 업로드 UI 확인
단위 테스트	`tests.test_web_gui` 등 실행	통과
실제 업로드	PNG를 `/api/upload-image`로 업로드	WordPress 미디어 URL 반환 확인
초안 반영	`drafts/ai-008.md`의 이미지 URL 확인	새 이미지 URL 삽입 확인
발행 글 반영	공개 URL HTML 확인	새 이미지 표시 확인
불필요한 캡션 제거	이미지 아래 설명 문구 검색	없음 확인
이미지 크기	공개 HTML에서 `width:100%` 확인	본문 너비 적용

이 단계가 bkit식 작업의 핵심입니다. AI 코딩에서는 “구현했다”와 “검증됐다”가 다릅니다. bkit은 이 둘을 분리해서 보게 만들고, 검증을 통과하지 못하면 다시 Do로 돌려보내는 구조를 강조합니다.

6. Act: 다음 작업에 남길 기준을 정한다

Act 단계에서는 이번 사례에서 얻은 운영 기준을 정리했습니다.

글 생성기의 본문 이미지는 기본적으로 실제 이미지 태그로 렌더링되어야 한다.
이미지 위치는 소개글 아래를 기본값으로 둔다.
이미지 생성 후 설명용 문구나 캡션을 자동으로 붙이지 않는다.
AI 생성 이미지와 이미지 업로드는 같은 결과 경로를 써야 한다. 즉 둘 다 WordPress 미디어 URL을 초안에 반영해야 한다.
발행된 글은 초안 수정 후 반드시 WordPress post와 다시 동기화해야 한다.
공개 URL에서 기존 이미지가 사라졌는지까지 확인한다.

이 기준은 다음 작업에서 다시 쓸 수 있습니다. bkit 관점에서 Act는 회고 문구를 남기는 단계가 아니라, 다음 작업의 실패 가능성을 줄이는 운영 자산을 만드는 단계입니다.

7. 실무 적용 순서

Codex와 bkit을 함께 쓴다면 작은 기능 개선도 다음 순서로 진행할 수 있습니다.

1. 사용자의 요구를 그대로 구현하지 말고, 먼저 검증 가능한 조건으로 쪼갭니다.

2. bkit의 Plan 관점으로 목적, 범위, 성공 기준을 정합니다.

3. Codex로 구현하되, 변경 파일과 외부 효과를 계속 구분합니다.

4. bkit의 Check 관점으로 테스트, 배포 화면, 실제 데이터 반영을 확인합니다.

5. 실패한 항목은 다시 Do로 돌려 수정합니다.

6. 반복될 기준은 Act 단계에서 문서, 스크립트, 테스트로 남깁니다.

이 흐름은 특히 블로그 자동 발행, 관리자 UI, WordPress 연동처럼 화면과 외부 시스템이 함께 움직이는 작업에 잘 맞습니다. 단순히 코드만 맞는 것이 아니라, 사용자가 보는 공개 결과까지 맞아야 하기 때문입니다.

8. 결론

`ai-008`의 의도는 Codex의 PDCA 개념을 추상적으로 소개하는 것이 아니라, Codex로 실제 작업을 하면서 bkit의 PDCA 흐름을 어떻게 활용하는지 보여주는 것이었습니다.

이번 블로그 운영 도구 사례에서 bkit의 가치는 분명했습니다. Plan은 요구사항을 검증 가능한 조건으로 바꾸게 했고, Do는 Codex의 구현 작업을 좁은 범위로 유지하게 했습니다. Check는 단위 테스트와 운영 검증을 분리하게 했고, Act는 다음 글 생성기 작업에 남길 기준을 만들게 했습니다.

AI 개발에서 중요한 것은 빠른 생성만이 아닙니다. 실제로는 요구사항을 잘게 나누고, 구현하고, 확인하고, 다음 작업에 남기는 반복 루프가 품질을 만듭니다. bkit은 이 루프를 Codex 같은 AI 코딩 환경에 적용하기 위한 실무형 하네스라고 볼 수 있습니다.

FAQ

Q. bkit을 쓰면 Codex가 자동으로 완벽한 코드를 만들까요?

아닙니다. bkit의 가치는 자동 생성보다 검증 가능한 작업 흐름에 있습니다. AI가 만든 결과를 계획, 설계, 구현, 검증, 개선의 루프로 통제하는 데 의미가 있습니다.

Q. 작은 블로그 기능 개선에도 PDCA가 필요한가요?

형식적인 문서까지 매번 만들 필요는 없습니다. 하지만 요구사항을 체크 항목으로 바꾸고, 구현 후 공개 화면에서 확인하는 최소 PDCA는 필요합니다. 이번 이미지 교체 작업처럼 작은 기능도 초안, 미디어, 발행 글, 공개 URL이 모두 연결되기 때문입니다.

Q. Codex와 bkit의 역할은 어떻게 나누면 되나요?

Codex는 실제 파일을 읽고 수정하고 명령을 실행하는 작업자에 가깝습니다. bkit은 그 작업자가 어떤 순서로 움직이고 무엇을 통과해야 하는지 정하는 운영 프레임워크에 가깝습니다.