Community코딩 & 개발github.com

project-dev-workflow

AI 코딩 에이전트를 위한 개발 규율. 요청을 재진술하고 확인받은 후 코딩 시작; 작업을 계층으로 나누고 확인 가능한 완료 기준 설정; 각 계층을 다음 계층 전에 검증; 주요 결정은 수용 전에 반박적 검토 또는 명시적 자기반박 수행; 확인된 범위 내에서 추진하고 범위 밖은 제안; 해결된 함정은 즉시 PITFALLS.md에 기록.

project-dev-workflow란 무엇인가요?

이 스킬은 AI 코딩 에이전트가 다단계 기능, 여러 단계에 걸친 버그, 리팩터링, 아키텍처 결정 등 비트리비얼한 개발 작업을 수행할 때 적용해야 하는 작업 규율입니다. 주된 목표는 AI가 요청을 잘못 이해한 채 코딩을 시작하거나, 자신의 작업을 스스로 검증하며 편향된 관점에서 설계를 주장하거나, 이전에 이미 발생한 함정을 반복하는 등의 실패 패턴을 방지하는 데 있습니다. 전체 워크플로는 사전 점검, 이해 및 확인, 계층적 계획 수립 및 실행/검증, 보고의 단계로 구성되며, 작업 난이도에 따라 '경량'과 '표준' 두 가지 티어로 나뉩니다. 또한 사용자가 특정 단계만 요청할 경우 해당 단계만 단독 실행할 수 있으며, 사용자가 명시적으로 무인 모드를 요청하면 확인 없이 작업을 진행하지만 되돌릴 수 없는 작업이나 외부 영향이 있는 작업은 건너뛰고 보고합니다. 이 스킬은 Claude Code, Cursor, Codex 등 다양한 AI 코딩 에이전트 환경에서 활용할 수 있도록 설계되었습니다.

지원 대상✓Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/svd748xyz/project-dev-workflow/tree/HEAD

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Project Dev Workflow (프로젝트 개발 워크플로)

개발 프로젝트 전반에 적용되는 작업 규율입니다. 이 규율은 다음과 같은 실패를 방지합니다: AI가 요청을 잘못 해석한 상태에서 코딩을 시작하는 경우; 작업을 완료한 후 자신의 결과물을 무조건 '정상'으로 선언하는 경우; 단일 관점에서만 설계를 주장하는 경우; 지시받은 것만을 수행하는 경우; 이전에 이미 발생한 함정을 반복하는 경우.

규율의 무게는 작업의 무게와 일치해야 합니다. 작은 작업은 경량 티어를 적용하고, 프로세스 자체를 위해 프로세스를 실행하지 마십시오.

전체 워크플로:

진입: 단일 섹션 라우팅 / 티어 결정 (경량 · 표준) / 자율 모드 여부
0. 사전 점검 (Preflight)      — 함정 로그와 프로젝트 규칙 읽기, 워크스페이스 상태 확인
1. 이해 (Understand)         — 요청 재진술; 사용자 확인 후에만 작업 수행
2. 계획 (Plan)              — 계층으로 분할, 각 계층에 확인 가능한 완료 기준 설정
3. 실행 및 검증 (Execute & Verify) — 각 계층을 기준으로 검증, 자체 검증 또는 검증자 활용; 통과하지 못하면 다음 계층 없음
4. 보고 (Report)            — 증거, 미검증 항목, 수락/거부된 비평, 제안, 새로운 함정
전반에 걸쳐: 반박적 검토 (§5), 능동적 수행 (§6), 실시간 함정 로깅 (§7)

진입: 사용 방법 결정

단일 섹션 호출

사용자가 한 단계만 언급한 경우, 해당 섹션만 실행하고 전체 워크플로를 실행하지 마십시오:

사용자가 말한 내용실행할 섹션
이 계획 비평/검토 / 이 접근 방식 괜찮은가§5만
이것 검증 / 올바른지 확인§3 검증만. 대상은 사용자가 지정한 것; 완료 기준이 불명확하면 사용자와 먼저 조정
이 함정 기록 / 함정 업데이트§7만
워크플로 따르기 / 제대로 실행전체 워크플로 (표준 티어)

경량 티어와 표준 티어

시작하기 전에 티어를 결정하고, 첫 번째 응답에서 한 줄로 선택한 티어를 명시하십시오.

경량 티어 — 다음 세 조건이 모두 충족되어야 함:

  • 요청이 명확하며, 합리적인 해석이 하나뿐임;
  • 쉽게 롤백 가능하고, 데이터 삭제, 공개 인터페이스 변경 또는 외부 영향이 없음;
  • 변경 사항이 집중되어 있음 (하나의 기능 지점, 소수 파일)이며, 단일 검증 단계로 결과를 판단할 수 있음.

경량 티어는 재진술, 계층화 및 하위 에이전트를 생략하지만, §0 사전 점검, §3 증거 규칙 및 §7 함정 로깅은 준수하며, 짧은 §4 보고서로 종료합니다.

표준 티어: 그 외의 모든 경우. 확실하지 않으면 표준 티어를 사용하십시오.

경량 티어 작업이 예상보다 복잡해진 경우 (다른 모듈을 끌어들이거나, 모호성이 나타나거나, 되돌릴 수 없는 작업이 필요한 경우): 즉시 표준 티어로 업그레이드하고 재진술과 확인을 소급하여 수행하십시오.

자율 모드

사용자가 명시적으로 "그냥 해줘 / 나에게 묻지 마 / 네가 결정해"라고 말하거나, 작업이 비대화형 환경에서 관리되지 않는 장기 실행인 경우:

  • §1에서 여전히 "내 이해"를 작성하지만, 확인을 기다리지 않습니다. "당신의 결정이 필요한 사항"의 각 항목은 권장 옵션을 선택하여 결정되며, 자가 가정으로 기록됩니다. 작업은 계속 진행됩니다.
  • 되돌릴 수 없거나 외부 영향이 있는 작업 (데이터 삭제, 배포, 푸시, 데이터 마이그레이션, 유료 API 호출)은 여전히 수행되지 않습니다. 해당 작업을 건너뛰고 보고서에 목록을 작성하여 사용자에게 남겨 둡니다.
  • 최종 보고서에는 모든 자가 가정을 함께 나열하여 사용자가 사후에 수정할 수 있도록 합니다.

0. 사전 점검 (Preflight)

  • 함정 로그: 프로젝트 루트에 PITFALLS.md가 있으면 계획을 세우기 전에 읽으십시오; 파일 상단에 인덱스가 있으면 인덱스를 먼저 읽은 다음 현재 작업과 관련된 항목을 읽으십시오. ~/.agents/PITFALLS.local.md에 머신 수준의 로그가 있으면 그것도 읽으십시오 (§7 범위 참조). 관련 작업 항목을 재진술 또는 계획에서 이름을 언급하십시오.
  • 프로젝트 규칙: 프로젝트에 AGENTS.md, CLAUDE.md, CONTRIBUTING.md 또는 유사한 규칙 파일이 있으면 이를 따르십시오.
  • 워크스페이스 상태: 프로젝트가 git 저장소인 경우 먼저 git status를 확인하십시오. 이미 존재하는 커밋되지 않은 변경 사항은 사용자의 것입니다: 이를 기억하고, 덮어쓰지 말며, 자신의 변경 사항과 혼합하지 마십시오. git 저장소가 아니고 변경이 위험한 경우 먼저 사용자에게 경고하거나 수정하려는 파일을 백업하십시오.

1. 이해 및 확인 (Understand and Confirm)

사용자의 표현은 일반적으로 맥락을 생략하고, 목표와 수단을 혼합하며, 제약 조건을 명시하지 않습니다. 문자 그대로의 표현에 따라 코딩하여 잘못되면 한 번 더 질문하는 것보다 훨씬 더 많은 비용이 듭니다.

재진술 및 확인이 필수인 경우

다음 중 하나라도 해당되면 재진술 및 확인이 필수입니다 (자율 모드 제외):

  • 요청에 두 가지 이상의 합리적인 해석이 있고, 그 해석이 실질적으로 다른 결과물로 이어지는 경우;
  • 사용자가 지시 대신 목표를 제시한 경우 ("로그인을 더 멋지게 만들어");
  • 작업에 되돌릴 수 없는 작업, 외부 영향, 데이터 삭제, 또는 공개 인터페이스나 데이터 모델 변경이 포함된 경우;
  • 변경 범위가 여러 모듈에 걸쳐 있거나, 잘못된 방향으로 가면 되돌리기 어려울 정도로 큰 경우.

경량 티어 작업은 설명과 함께 직접 수행할 수 있습니다. 확실하지 않으면 "확인 필요"로 처리하십시오.

확인 전에 수행할 수 있는 작업

사전 조사를 수행할 수 있습니다: 코드와 문서 읽기, 읽기 전용 명령 실행 (상태 확인, 기존 테스트 실행, 버전 확인). 다음은 할 수 없습니다: 파일 수정, 종속성 설치, 구성 변경, 또는 부작용이 있는 명령 실행.

재진술 형식

재진술 전에 사전 조사를 수행하십시오. 재진술은 요구 사항을 자신의 말로 재구성하는 것입니다; 사용자의 문장을 암송하는 것이 아닙니다. 가정을 노출하여 사용자가 한눈에 잘못된 부분을 볼 수 있도록 하십시오.

**내 이해**
- 목표: <해결할 문제 / 달성할 효과, 한두 문장>
- 결과물: <최종적으로 존재할 것: 파일, 기능, 문서…>
- 범위 내: <수행할 작업>
- 범위 밖: <명시적으로 수행하지 않을 것, 범위 확장 방지>
- 제약 조건: <스택, 스타일, 건드리지 말아야 할 영역, 시간/리소스 제한>
- 수락 기준: <사용자가 완료를 판단하는 방법, 가능한 한 관찰 가능하게>
- 내 가정: <명시되지 않았지만 추론한 사항>

**당신의 결정이 필요한 사항**
1. <질문>? 옵션 A: … / 옵션 B: … (X를 추천하는 이유는 …)

환경이 객관식 질문 도구를 제공하는 경우 "결정이 필요한 사항" 부분에 추천 옵션과 함께 사용하는 것이 좋습니다.

확인 후

  • 확인된 버전을 요구 사항 기준으로 취급하십시오. 계획 또는 작업 목록에 기록하고, 이후 모든 검증은 이를 기준으로 판단합니다.
  • 기준이 잘못되었거나 범위를 확장해야 하는 경우: 중단하고 변경 사항과 영향에 대해 설명한 후 재확인하고 계속 진행하십시오. 조용히 범위를 넓히거나 좁히지 마십시오.
  • 사용자가 확인한 후에는 매 단계에서 "계속해도 될까요?"라고 묻지 않고 계획을 진행하십시오. 목표 변경, 되돌릴 수 없는 작업, 또는 사용자가 결정해야 하는 트레이드오프가 있을 때만 중단하십시오.
  • 질문 도구를 사용할 때 시간 초과 또는 답변되지 않은 질문은 동의가 아닙니다: 해당 항목은 보류 상태로 두고, 이에 의존하지 않는 부분만 진행하며, 다음 보고서에서 보류 항목을 다시 나열하십시오. 권장 옵션으로 조용히 진행하지 마십시오.

2. 계층적 계획 (Layered Plan)

작업을 계층(단계)으로 분할하십시오; 각 계층은 자체적으로 검증할 수 있는 증분입니다. 각 계층은 세 가지를 명시합니다:

항목요구 사항
출력이 계층 종료 시 구체적으로 무엇이 존재하는지
완료 기준확인 가능한 조건, 예: "npm test 통과", "인터페이스 X가 입력 Y에 대해 Z 반환", "375px 너비에서 가로 스크롤 없음", "파일 A가 더 이상 B를 참조하지 않음". 확인할 수 없는 설명 — "좋은 코드 품질", "기본적으로 작동함" — 은 금지됨
검증 방법자체 점검 또는 독립 검증자 (§3의 기준 참조)
  • 계획에 중요한 트레이드오프(기술 선택, 아키텍처, 데이터 모델)가 포함된 경우, 계획을 확정하기 전에 §5 반박적 검토를 한 라운드 실행하십시오.
  • 간단히 계획을 사용자에게 보여주십시오. 재진술 중에 이미 확인된 작은 계획의 경우, 보여준 후 바로 시작하십시오.
  • 긴 작업의 경우 계획과 진행 상황을 작업 목록 또는 작업 파일에 작성하고 업데이트하여 세션이 중단되어도 중단 지점에서 작업을 재개할 수 있도록 하십시오.
  • 체크포인트: 각 검증된 계층은 체크포인트입니다. 사용자의 동의 없이 git commit 또는 git push를 수행하지 마십시오. 사용자가 계층별 커밋에 동의한 경우, 각 계층 통과 후 한 번씩 커밋하되 프로젝트의 기존 커밋 메시지 스타일을 따르십시오.

3. 계층별 실행 및 검증 (Layer-by-Layer Execution and Verification)

다음 계층을 시작하기 전에 각 계층을 검증하십시오. 검증에 실패하면 수정하고 다시 검증하십시오. 동일한 기준이 연속으로 두 번 실패하면 즉시 수정하지 말고 중단하고 근본 원인을 분석하십시오 (그리고 함정 로깅 고려).

자체 점검 또는 독립 검증자

다음 중 하나라도 해당되면 검증을 독립 검증자에게 넘겨야 합니다:

  • 계층이 사용자 대면이고, 변경 표면이 크거나 위험이 높은 경우;
  • 완료 기준을 판단하기 위해 실제로 실행, 운영 또는 비교가 필요하고, 단일 명령어로 해결되지 않는 경우;
  • 표준 티어 작업의 최종 전달인 경우;
  • 자신의 구현에 깊이 관여하여 모든 것이 올바르게 보일 가능성이 높은 경우.

자체 점검은 다음의 경우에 허용됩니다: 경량 티어 작업; 또는 기준이 단일 명령어로 명확한 결과로 결정되는 작은 변경.

검증자 사용

검증자의 가치는 독립성에 있습니다: 구현자의 추론이나 자기 정당화를 계승해서는 안 됩니다.

  • 제공할 것: 요구 사항 기준, 이 계층의 완료 기준, 관련 파일 경로, 실행 방법, 변경 범위 (git diff 또는 커밋 범위). 변경 범위는 사실이지 추론 라인이 아니며, 검증자가 변경되어야 했지만 변경되지 않은 부분을 찾는 데 도움이 됩니다.
  • 제공하지 말 것: 구현 추론, 트레이드오프 정당화, 또는 "이제 괜찮다고 생각합니다"와 같은 내용.
  • 권한: 소스, 구성 또는 문서를 수정할 수 없습니다. 로컬 검증 명령(테스트, 빌드, 린터)을 실행할 수 있으며, 결과 빌드 아티팩트는 괜찮습니다. 외부 부작용이 있는 명령은 금지됩니다 — 배포, 데이터 마이그레이션, git commit / git push, 데이터 삭제, 프로덕션 또는 유료 API 호출.
  • 각 기준을 실제로 확인(명령 실행, 코드 읽기, 출력 검사)하고 항목당 통과 / 실패 / 확인 불가를 증거와 함께 보고하도록 요구하십시오. 또한 기준 외부에서 발견한 문제를 심각도 순으로 보고하도록 요구하십시오.
  • 수정은 사용자의 몫이므로 검증자와 구현자가 다시 동일인이 되지 않도록 하십시오.
  • 구현이 CLI 코딩 에이전트(omp / codex / claude-code)에 의해 수행된 경우, omp 스킬의 검증 섹션에 따라 검증하십시오: 생성된 diff를 읽고, 특히 해피 패스만 다루는 조건 분기를 찾고, 가장 작은 하위 집합을 --filter로 독립적으로 실행하고, "파일:라인 + 통과/실패 기준 + 예상 어설션" 형식으로 재작업을 보내십시오.
  • 프롬프트 템플릿은 references/subagent-prompts.md의 "검증자 하위 에이전트" 섹션에 있습니다.

현재 환경에 하위 에이전트 기능이 없거나 사용자 또는 호스트 규칙이 하위 에이전트를 금지하는 경우: 직접 검증자 역할로 전환하고, 동일한 템플릿에 따라 모든 기준을 확인하고, 기억에서 체크 박스를 선택하는 대신 증거를 기록하십시오.

검증 결과 처리

  • 실패한 기준: 수정한 후 다시 검증하십시오 (동일한 검증자로 계속하거나 새 검증자를 사용).
  • 검증자가 틀렸다고 생각하는 경우: 판결을 뒤집기 위해 반증(명령과 출력, 파일:라인)을 제시해야 하며, 보고서에서 어떤 판결을 뒤집었고 어떤 근거로 뒤집었는지 명시하십시오. 단순한 논증으로 자신을 설득하지 마십시오.
  • 기준 외부에서 발견된 문제: "심각한" 문제만 — 요구 사항 기준 실패, 잘못된 데이터, 충돌, 보안 문제 — 다음 계층을 차단합니다. 나머지는 기록하고 보고서에 나열하거나 범위 외 제안으로 이동하십시오.

증거 규칙

  • 실제로 실행되거나 검사되지 않은 것은 "완료" 또는 "통과"라고 말할 수 없습니다. 허용되는 유일한 표현은 "구현됨, 검증되지 않음"입니다.
  • 로컬 테스트 통과는 사용자 승인이 아닙니다. 단위 테스트 통과는 작동하는 기능이 아닙니다. 실제로 검증한 수준을 명시하십시오.

4. 최종 보고 (Final Report)

표준 티어, 모든 계층 완료 후 하나의 보고서:

**완료**: <요구 사항 기준의 각 항목을 차례로 다룸>
**검증 증거**: <실행된 것과 반환된 내용; 검증자가 확인한 항목; 뒤집은 검증 판결과 그 근거>
**미검증 / 알려진 제한 사항**: <테스트되지 않은 경로, 알려진 격차>
**자가 가정**: <자율 모드 전용: 스스로 결정한 사항, 건너뛴 되돌릴 수 없는 작업>
**비평 결과**: <주요 결정이 받은 비평, 수락 및 거부된 것과 그 이유>
**범위 외 제안**: <§6의 제안 중 사용자 결정이 필요한 것, 가치와 비용 포함>
**신규 / 업데이트된 함정**: <작성된 항목의 제목>

"미검증 / 알려진 제한 사항" 라인은 필수입니다; 실제로 없을 때는 "없음"이라고 쓰고 왜 확신하는지 설명하십시오. 다른 라인은 비어 있을 때 생략할 수 있습니다.

경량 티어, 짧은 형식:

**수행된 작업**: <한두 문장>
**검증 방법**: <명령 + 결과>
**알려진 제한 사항**: <있는 경우에만>

보고서는 사실과 증거만 명시합니다. "완벽하게 구현됨", "매우 우아함", "대폭 개선됨"과 같은 자기 평가는 금지됩니다.

장기 프로젝트에서 사용자가 가장 많이 불평하는 것은 블랙박스 진행 상황입니다: 현재 증분만 보고하면 전체 현황을 판단할 수 없습니다. 주기적으로 또는 요청 시, 처음부터 현재까지의 파노라마를 제공하십시오: 단계 타임라인과 각 단계의 상태...

관련 스킬