Codex Devflow — 스킬 프로젝트 소개

구현 전의 질문을 서로 다른 역할로 나누기

Codex Devflow에서는 무엇을 만들지 정할 때 계획을, 구조와 실패 조건을 확인할 때 검토를, 소유 파일을 나눌 때 분담을 사용합니다. 저는 이 일을 한 명령으로 묶지 않았습니다. 서로 이어지는 작업이어도 필요한 판단과 결과가 다르기 때문입니다.

번들에는 각 역할을 독립된 스킬로 두었습니다. 필요한 것만 설치하고 사용할 수 있어야 했습니다. 개발 계획이 필요한 요청에 작업 분담까지 자동으로 붙이거나, 프로젝트 설명을 정리하는 요청을 구현 계획으로 확대하지 않도록 진입 조건도 나눴습니다.

이 프로젝트의 핵심은 새로운 실행 런타임이 아니라 작업 운영 규칙입니다. 모델을 호출하는 엔진이나 작업 상태 서비스를 만드는 대신, 구현 전에 확인할 판단과 다음 단계로 전달할 산출물을 정리했습니다. 작은 번들이 맡을 책임을 분명히 하는 선택이었습니다.

계획서에는 목표와 제외할 일을 함께 넣었습니다

개발 계획 스킬에는 목적, 범위, 제외 범위, 관련 자료, 단계별 자체 테스트와 완료 조건을 요구했습니다. 할 일만 나열하면 관련 있는 작업이 계속 붙을 수 있어, 이번에 하지 않을 것도 같은 문서에 남기도록 했습니다.

계획의 진행 표시는 실제 작업과 맞춰 갱신합니다. 과거 계획을 새 문서로 덮어쓰지 않고, 불분명하거나 위험한 일은 별도 단계나 후속 항목으로 두도록 했습니다. 문서를 만들었다는 이유로 구현까지 끝난 상태가 되지 않도록 한 것입니다.

계획 예제에는 배포 자동화와 외부 API 연동을 제외했습니다. 이것은 실제 제품 기능의 구현 결과가 아니라, 범위와 의존성을 어떻게 나타내는지 보여 주는 예제입니다. 예제에서 제외한 기능이 다른 모든 프로젝트에서도 금지되는 것은 아닙니다. 해당 목표에서 무엇을 먼저 끝낼지 판단하는 형식으로 사용합니다.

설계 검토가 계획을 다시 바꿀 수 있게

검토 스킬은 준비됨, 수정 필요, 진행 불가의 판단을 먼저 내고 중요한 위험을 정리하도록 구성했습니다. 아키텍처와 데이터 흐름뿐 아니라 소유 경계, 실패 조건, 테스트, 되돌릴 방법까지 살핍니다. 보기 좋은 계획서인지보다 구현 전에 바꿀 부분이 있는지를 확인하는 역할입니다.

예시 계획에서는 기존 모듈을 확장하는 구조를 사용하되 공유 계약은 주의가 필요한 항목으로 남겼습니다. 뒤에서 여러 담당이 함께 사용할 타입을 먼저 고정해야 한다는 조건입니다. 검토가 단순한 통과 표시라면 이 주의 사항이 실제 작업 순서로 옮겨지지 않을 수 있습니다.

그래서 받아들인 권고는 계획에 반영할 수 있게 했습니다. 공유 파일의 소유자가 불분명하거나 정상 입력만 검사하는 테스트가 있다면 구체적인 수정 항목으로 남깁니다. 검토 결과와 구현할 계획이 서로 다른 문서에서 어긋나지 않아야 다음 담당이 같은 전제를 가집니다.

예시에서는 공유 타입을 먼저 확정했습니다

함께 만든 분담 예제는 공통 타입, backend, CLI/TUI, 문서와 검사로 나뉩니다. 공통 타입은 먼저 끝내고 backend와 UI는 그 결과를 기반으로 작업합니다. 문서와 전체 검사는 두 구현 결과 뒤에 이어집니다. 모든 단계가 동시에 움직이는 구조로 만들지 않았습니다.

담당별 표에는 소유 파일뿐 아니라 수정하지 않을 파일도 적었습니다. backend 담당은 UI 경로를 바꾸지 않고, UI 담당은 backend 경로를 바꾸지 않는 방식입니다. 읽기 맥락은 공유하더라도 쓰기 책임은 한곳에 있어야 합니다.

통합 순서는 공통 작업, 독립 구현, 공유 연결과 문서, 전체 검수로 정했습니다. 각 담당의 독립 검사를 통과한 뒤에도 전체 결과가 맞는지 확인합니다. 공유 타입을 받은 구현들이 실제로 이어지는지까지 봐야 하기 때문입니다.

프로젝트 설명도 구현과 연결해야 했습니다

2026년 4월 19일에는 프로젝트 설명을 정리하는 스킬을 번들에 추가했습니다. 계획과 검토, 분담으로 작업을 진행해도 프로젝트를 처음 보는 사람은 목적과 설치 방법, 실행 명령을 별도로 읽습니다. 그 설명이 실제 구조와 연결되도록 역할을 하나 더 둔 것입니다.

설명 정리에서는 실제로 존재하는 기술과 기능만 소개하고, 명령과 파일 경로를 확인하도록 했습니다. 자동화 파이프라인이나 배포 패키지가 없는데 있는 것처럼 표시하지 않습니다. 시각 표지를 붙이더라도 그 표지가 가리키는 기능과 검사 기반이 있어야 합니다.

작은 도구에 큰 프로젝트의 문서 형식을 그대로 가져오지도 않도록 했습니다. 적용할 섹션을 먼저 고르고 기존의 중요한 정보는 보존합니다. 계획의 범위를 지키는 것과 소개 문서의 범위를 지키는 것은 같은 문제로 이어집니다. 설명이 구현보다 앞서 나가면 다음 사용자가 잘못된 전제로 시작하게 됩니다.

네 역할을 모두 쓰는 것이 목표는 아닙니다

새 작업에서는 요구에 맞는 진입점을 고릅니다. 목표와 경계가 없으면 계획부터, 계약과 실패 조건이 불분명하면 검토부터, 독립된 구현을 나눠야 하면 분담을 사용합니다. 이미 구현된 도구를 설명하려면 실제 명령과 구조를 확인하며 소개를 정리합니다.

단계가 필요하다는 이유만으로 별도 시스템을 계속 추가하지 않습니다. 이 번들에 포함한 스킬도 각자의 짧은 지시와 필요한 참조만 갖도록 했습니다. 제공하지 않는 실행 기능을 플러그인의 능력처럼 보이게 만들지 않는 것도 이 구조의 책임입니다.

어느 스킬을 썼는지보다 그 판단이 다음 작업에 남았는지를 확인합니다. 계획에서 정한 범위, 검토에서 발견한 위험, 담당별 소유 파일, 실제 기능을 설명하는 문서가 서로 맞아야 합니다.