pdca 라이브러리를 이해하려면 먼저 PDCA를 단순한 보고서 양식으로 보면 안 됩니다. PDCA는 Plan, Do, Check, Act를 반복하면서 작업의 기준과 결과를 계속 맞추는 운영 루프입니다. 개발 작업에서는 요구사항을 정리하고, 구현하고, 검증하고, 다음 개선 기준을 남기는 흐름으로 사용할 수 있습니다.
bkit 라이브러리는 이 흐름을 Codex나 다른 AI 개발 도구 안에서 반복 가능한 문서와 명령 체계로 다루기 위한 도구입니다. 핵심은 AI에게 “알아서 해줘”라고 맡기는 것이 아니라, AI가 따라야 할 계획, 설계, 구현, 검증, 개선의 단계를 명확히 만드는 데 있습니다. 이 글은 pdca 라이브러리의 개념과 bkit 라이브러리 설치 방법을 함께 설명하고, Codex CLI에서 `$pdca`를 활성해 쓰는 기본 예시까지 정리합니다.
pdca 라이브러리는 무엇을 해결하려는가
AI 코딩 도구를 쓰면 작업 속도는 빨라집니다. 하지만 속도가 빨라질수록 “무엇을 기준으로 성공이라고 볼 것인가”가 흐려지기 쉽습니다. 한 번의 프롬프트로 코드를 고치고, 다음 프롬프트로 테스트를 돌리고, 다시 다른 파일을 수정하다 보면 요구사항과 검증 기준이 대화 안에서 흩어집니다.
pdca 라이브러리는 이 문제를 줄이기 위한 작업 관리 구조로 이해할 수 있습니다. Plan 단계에서는 목표, 범위, 성공 기준을 적습니다. Do 단계에서는 실제 구현을 진행합니다. Check 단계에서는 계획과 결과가 맞는지 비교합니다. Act 단계에서는 확인한 차이를 다음 작업 기준으로 반영합니다.
이 구조는 거창한 프로젝트에만 필요한 것이 아닙니다. 블로그 글 생성기 하나를 고치는 작업에도 적용할 수 있습니다. 예를 들어 “본문 이미지가 누락되지 않게 하라”는 요청이 있다면 Plan에서는 이미지가 필요한 조건과 성공 기준을 적고, Do에서는 코드와 초안을 고치며, Check에서는 실제 이미지 파일과 WordPress 반영 여부를 확인하고, Act에서는 같은 누락이 반복되지 않도록 테스트나 가이드를 보강합니다.
bkit 라이브러리는 pdca를 어떻게 도구화하는가
bkit 라이브러리는 PDCA를 문서와 명령 흐름으로 다룰 수 있게 돕는 계층입니다. 프로젝트 안에 `docs/01-plan`, `docs/02-design`, `docs/03-analysis`, `docs/04-report` 같은 구조를 두고, 기능별 계획서와 설계서, 분석 결과, 완료 보고서를 연결합니다. 이렇게 하면 Codex가 작업을 시작할 때 현재 단계와 다음 단계를 확인할 수 있습니다.
중요한 점은 bkit이 코드를 대신 잘 짜주는 마법이 아니라는 것입니다. bkit의 역할은 작업 기준을 잃지 않도록 붙잡아 주는 것입니다. Codex가 빠르게 파일을 고칠 수 있더라도, 어떤 파일을 왜 고쳤는지, 어떤 검증을 통과해야 하는지, 다음 작업에서 무엇을 반복하지 말아야 하는지를 남기지 않으면 같은 문제가 다시 생깁니다.
pdca 라이브러리와 bkit 라이브러리를 함께 보면 다음과 같이 역할을 나눌 수 있습니다.
| 구분 | 역할 | 실제 의미 |
|---|---|---|
| PDCA | 작업을 반복 개선하는 사고 틀 | 계획, 실행, 검증, 개선을 한 주기로 묶음 |
| pdca 라이브러리 | PDCA 단계를 명령과 문서로 다루는 기능 | `$pdca plan`, `$pdca analyze` 같은 단계 실행 |
| bkit 라이브러리 | 프로젝트 수준의 PDCA 상태와 산출물 관리 | 상태 파일, 문서 위치, 단계 전환 기준 관리 |
| Codex CLI | 사용자가 명령을 실행하는 인터페이스 | `$pdca` 프롬프트를 통해 작업 지시 |
bkit 라이브러리 설치 전에 확인할 것
bkit 라이브러리를 설치하기 전에 먼저 프로젝트가 어떤 방식으로 관리될지 정해야 합니다. 단순 정적 사이트인지, 백엔드가 있는 동적 앱인지, 여러 서비스가 얽힌 엔터프라이즈 구조인지에 따라 필요한 문서와 검증 수준이 달라집니다. 작은 프로젝트라면 모든 산출물을 무겁게 만들 필요가 없습니다.
설치 전에는 다음 항목을 확인하는 편이 좋습니다.
- 프로젝트 루트가 어디인지 확인합니다.
- Codex CLI가 해당 루트에서 실행되는지 확인합니다.
- `AGENTS.md` 같은 작업 지시 문서가 있는지 확인합니다.
- `docs/.pdca-status.json`을 둘 위치를 정합니다.
- 이미 쓰고 있는 테스트 명령이나 배포 명령이 무엇인지 정리합니다.
이 단계가 필요한 이유는 단순합니다. bkit은 프로젝트의 작업 흐름을 정리하는 도구이므로, 프로젝트 루트와 문서 위치가 흔들리면 PDCA 상태도 흔들립니다. 설치 자체보다 중요한 것은 설치 후 Codex가 같은 기준을 계속 읽을 수 있게 만드는 것입니다.
bkit 라이브러리 설치 방법의 실행 예시
bkit 설치 방식은 사용하는 배포 방식과 저장소 구조에 따라 달라질 수 있습니다. 가장 안전한 설명은 “프로젝트 루트에서 bkit 관련 패키지나 플러그인을 설치하고, Codex가 읽을 수 있는 스킬과 문서 구조를 확인한다”는 순서입니다. 아래 예시는 Codex CLI를 사용하는 로컬 프로젝트 기준의 흐름입니다.
먼저 Codex CLI와 Node 런타임이 있는지 확인합니다. bkit이 Node 기반 도구나 MCP 서버와 함께 쓰이는 환경이라면 Node 버전 확인이 필요합니다. 그다음 bkit 패키지나 플러그인을 프로젝트 정책에 맞게 설치합니다.
이미 bkit이 Codex 플러그인이나 로컬 스킬 묶음으로 제공되는 환경이라면 설치 명령이 달라질 수 있습니다. 이 경우에는 패키지를 새로 설치하기보다 `.bkit-codex`, `.agents/skills`, `AGENTS.md`가 프로젝트 루트에서 정상적으로 보이는지 확인하는 것이 먼저입니다.
정상적으로 준비되었다면 `pdca` 스킬 문서가 보여야 합니다. 예를 들어 `C:CODEX.bkit-codex.agentsskillspdcaSKILL.md` 같은 경로에 스킬 설명이 있고, 그 안에 `$pdca plan`, `$pdca design`, `$pdca analyze`, `$pdca report` 같은 명령 흐름이 정리되어 있으면 Codex가 PDCA 작업 방식을 읽을 수 있습니다.
Codex CLI에서 pdca 라이브러리를 활성하는 방법
Codex CLI에서 pdca 라이브러리를 쓴다는 것은 별도의 GUI 버튼을 누른다는 뜻이 아닙니다. 보통은 프롬프트에서 `$pdca` 스킬을 명시해 Codex가 해당 스킬 지시를 읽고 작업하도록 만드는 방식입니다. 가장 기본적인 예시는 다음과 같습니다.
이 프롬프트는 현재 프로젝트의 PDCA 상태를 확인하라는 의미입니다. 상태 파일이 있다면 현재 기능이 어느 단계에 있는지 확인하고, 다음 단계가 무엇인지 제안할 수 있습니다.
새 기능을 시작할 때는 다음처럼 계획 단계를 먼저 요청합니다.
이 요청은 `keyword-tags-flow`라는 기능에 대해 계획 문서를 만들라는 뜻입니다. 계획에는 목표, 범위, 성공 기준, 위험, 검증 방법이 들어가야 합니다. 계획 없이 바로 구현하면 빠를 수는 있지만, 나중에 무엇을 기준으로 통과라고 판단했는지 설명하기 어렵습니다.
설계 단계는 다음처럼 진행합니다.
이 단계에서는 어떤 파일을 바꾸고, 어떤 데이터가 오가며, 어떤 테스트로 검증할지 정리합니다. 예를 들어 글 생성기에서 researcher가 뽑은 키워드를 writer가 WordPress 태그로 반영해야 한다면, `research.md`, `agent_pipeline.py`, draft frontmatter, 검증 테스트가 설계 범위에 들어갑니다.
구현 후에는 분석을 실행합니다.
분석 단계는 계획과 구현이 맞는지 비교합니다. 설계에는 “키워드가 tags에 반영된다”고 되어 있는데 실제 draft에 태그가 없다면 gap으로 기록합니다. 이 gap이 남아 있으면 `$pdca iterate keyword-tags-flow`로 다시 개선하고, 충분히 맞으면 `$pdca report keyword-tags-flow`로 완료 보고서를 만듭니다.
설치 후 바로 확인해야 하는 파일과 상태
bkit 라이브러리를 설치하고 `$pdca`를 활성했다면 바로 글이나 코드를 고치기보다 상태 확인부터 해야 합니다. Codex가 실제로 PDCA 스킬을 읽고 있는지, 프로젝트 문서 위치를 찾는지, 상태 파일을 해석할 수 있는지 확인해야 합니다.
상태 파일이 없다면 새로 만들 수 있지만, 이미 있는 프로젝트라면 함부로 초기화하면 이전 작업 기록이 끊길 수 있습니다. 이때는 `$pdca status`로 상태를 먼저 확인하고, 없는 경우에만 `$pdca plan {feature}`부터 시작하는 편이 안전합니다.
자주 생기는 오해
첫 번째 오해는 pdca 라이브러리를 설치하면 자동으로 좋은 계획이 만들어진다는 생각입니다. 도구는 형식을 제공할 수 있지만, 좋은 계획은 사용자가 작업 목적과 성공 기준을 분명히 줄 때 만들어집니다. “글을 좋게 고쳐라”보다 “개념 설명 글은 정의, 비교, 예시, 한계를 포함해야 한다”가 훨씬 좋은 입력입니다.
두 번째 오해는 bkit 라이브러리가 Codex의 대체물이라는 생각입니다. bkit은 Codex가 일하는 기준을 정리하는 도구에 가깝습니다. Codex CLI는 실행 인터페이스이고, bkit은 작업 상태와 산출물을 관리하며, pdca 스킬은 Plan, Design, Do, Check, Act의 명령 흐름을 제공합니다.
세 번째 오해는 PDCA가 문서를 늘리는 방식이라는 생각입니다. 실제 목적은 문서를 늘리는 것이 아니라 반복 실수를 줄이는 것입니다. 작은 작업에서는 짧은 계획과 짧은 검증 기록만으로 충분합니다. 중요한 것은 길이가 아니라 다음 작업자가 같은 기준을 이해할 수 있는가입니다.
적용 여부를 판단하는 기준
pdca 라이브러리와 bkit 라이브러리는 반복되는 작업에 특히 잘 맞습니다. 블로그 글 생성기, 배포 스크립트, UI 검증, 테스트 자동화, 운영 문서 관리처럼 같은 유형의 작업이 계속 반복되는 경우 효과가 큽니다. 반대로 한 번 쓰고 버리는 실험에는 과하게 느껴질 수 있습니다.
적용 여부는 다음 관점과 기준으로 판단할 수 있습니다. 도구를 설치할 수 있는가만 보지 말고, 반복 작업의 기준을 남길 필요가 있는지 함께 봐야 합니다.
- 같은 문제가 두 번 이상 반복되는가?
- 작업 기준을 대화가 아니라 문서나 테스트로 남겨야 하는가?
- Codex가 여러 파일을 수정하고 검증까지 해야 하는가?
- 실패했을 때 되돌릴 기준이 필요한가?
- 다음 작업에서도 같은 규칙을 재사용해야 하는가?
이 질문에 대부분 “예”라고 답한다면 bkit과 pdca 라이브러리를 적용할 가치가 있습니다.
결론
pdca 라이브러리는 Codex 작업을 계획, 실행, 검증, 개선의 루프로 묶는 개념입니다. bkit 라이브러리는 그 루프를 프로젝트 문서와 상태 파일, 스킬 명령으로 다룰 수 있게 돕습니다. 설치 방법에서 중요한 것은 명령 하나를 외우는 것이 아니라, Codex CLI가 프로젝트 루트, 스킬 문서, PDCA 상태를 같은 기준으로 읽게 만드는 것입니다.
처음 시작할 때는 `$pdca status`로 현재 상태를 확인하고, 새 기능은 `$pdca plan {feature}`부터 시작하는 편이 안전합니다. 그다음 design, do, analyze, iterate, report 순서로 작업을 진행하면 Codex의 빠른 실행력을 유지하면서도 작업 근거와 검증 기록을 남길 수 있습니다.
더 확인할 자료
아래 링크는 이 글의 기준과 배경을 확인할 수 있는 공식 자료입니다.