Claude Devflow — 스킬 프로젝트 소개

테스트 통과와 리뷰 완료를 따로 두기

테스트가 통과해도 코드 리뷰에서 살펴볼 위험은 남을 수 있습니다. Claude Devflow는 이 차이를 두고 계획, 병렬 분담, 테스트 수정, 코드 리뷰, 릴리스 문서를 다섯 역할로 구성했습니다. 테스트는 정한 조건에서 결과가 맞는지 확인하고, 리뷰는 그 조건 밖의 위험이나 잘못된 계약을 살핍니다.

테스트를 통과하면 코드 리뷰도 끝났다고 취급하는 구조로 만들지 않았습니다. 반대로 검토 의견이 있다는 이유만으로 실패한 테스트를 통과 상태로 바꾸지도 않습니다. 각 단계에는 입력과 산출물을 따로 정하고 다음 역할이 무엇을 받아야 하는지 연결했습니다.

이 번들은 Claude Code의 작업 도구와 인수인계 방식을 사용하는 운영 규칙입니다. 자체적으로 새로운 실행 엔진을 제공하는 구조는 아닙니다. 스킬마다 호출 조건과 사용할 도구를 정해, 요청이 어느 확인 단계인지 분명하게 드러내도록 했습니다.

계획이 끝난 뒤 구현 전에 한 번 더 검토하기

2026년 4월 19일에는 개발 계획 스킬에 엔지니어링 검토 단계를 추가했습니다. 생성된 계획을 구현 전에 다시 읽고 아키텍처, 공유 계약, 경계값, 보안, 테스트 전략을 확인하도록 바꿨습니다. 검토 결과도 준비됨, 수정 필요, 진행 불가로 나누어 계획에 남깁니다.

계획 스킬의 자체 검토와 별도 심층 리뷰도 구분했습니다. 자신의 결과를 점검한 뒤 더 살펴볼 위험이 있으면 다른 리뷰 호출로 넘길 수 있게 했습니다.

계획의 각 태스크에는 구체적인 대상과 성공 조건을 넣습니다. “인증 구현”처럼 넓게 적는 대신 어느 모듈에서 어떤 입력과 결과를 다룰지 정합니다. 정상 입력뿐 아니라 오류 경로의 테스트를 계획에 남겨야 수정 단계도 그 조건을 기준으로 움직일 수 있습니다.

실패 출력에서 원인을 좁히는 순서를 정했습니다

테스트 수정 스킬은 먼저 프로젝트의 테스트 명령을 찾고 전체 출력을 받아 실패한 테스트와 위치, 메시지, 호출 흐름을 정리합니다. 빌드 오류, 기대값 불일치, 실행 중 예외, 시간 초과를 나눠 조사 방향을 잡도록 했습니다.

그 뒤에 실패한 테스트와 관련 소스를 함께 읽습니다. 같은 오류 메시지라도 import 경로가 틀린 것인지, 데이터 변환이 다른 것인지, 외부 서비스가 응답하지 않는 것인지를 구분해야 합니다. 오류 문자열을 보고 곧바로 넓은 코드를 수정하는 방식으로 두지 않았습니다.

원인 조사만 요청한 경우에는 여기서 멈추도록 했습니다. 호출 경로와 가설, 수정 제안을 남기되 실제 변경은 하지 않는 모드입니다. 실패 원인을 알고 싶은 요청과 코드를 고쳐 달라는 요청이 같은 실행으로 흘러가지 않게 경계를 나눴습니다.

한 번의 수정과 다시 검사할 범위를 작게

수정 루프에서는 한 번에 한 관심사만 바꾸고 실패와 관련 없는 코드는 건드리지 않도록 했습니다. 기대 결과가 맞는데 구현이 틀렸다면 구현을 고칩니다. 테스트 자체가 잘못된 조건을 요구할 때만 테스트를 수정하도록 기준을 적었습니다.

먼저 실패했던 테스트를 다시 실행하고, 통과하면 전체 테스트로 이어집니다. 작은 확인은 수정이 해당 문제에 영향을 주었는지 빠르게 알려 주지만, 다른 동작까지 유지되는지는 전체 검사에서 봐야 합니다. 두 검사를 한 번의 통과 표시로 합치지 않은 이유입니다.

반복에도 종료 조건을 뒀습니다. 기본 최대 다섯 번, 같은 오류가 세 번 연속 반복되면 멈추고 현재 상태를 보고합니다. 외부 서비스나 설계 수준의 문제가 드러난 경우도 무한히 코드를 고치는 대신 필요한 판단을 남깁니다. 반복 횟수가 많다는 사실보다 접근이 달라졌는지와 어떤 실패가 남았는지가 중요합니다.

결제 시나리오는 단계 연결을 보여 주는 예제입니다

함께 만든 결제 모듈 예제에서는 공유 타입을 먼저 정의하고, 결제 연동과 웹훅 처리의 경로를 나눕니다. 그 뒤 테스트 수정과 코드 리뷰, 변경 설명으로 이어지는 모습을 보여 줍니다. 이 예제의 실패 수와 수정 반복은 사용법을 설명하는 시나리오이며 실제 결제 서비스의 장애 기록으로 사용하지 않습니다.

예제에서 보여 준 중요한 차이는 테스트 후에도 리뷰가 남아 있다는 점입니다. 기대한 입력이 통과해도 서명 비교 방식이나 외부 호출의 대기 조건을 다시 살필 수 있습니다. 리뷰는 코드 변경에서 정확성, 보안, 성능, 테스트 공백을 확인하고 심각도에 따라 필요한 수정과 제안을 나눕니다.

릴리스 문서는 그 뒤 실제 변경을 사용자 관점으로 설명하도록 했습니다. 구현하지 않은 기능이나 존재하지 않는 배포 기반을 소개하지 않습니다. 변경 이력과 버전 사이의 차이를 읽고, 무엇이 추가되거나 수정됐는지 정리하는 역할입니다. 문서가 앞선 검증을 대신하는 것은 아닙니다.

실행 명령에도 별도 확인 지점을 두었습니다

번들에는 Bash 호출 전에 일부 위험 명령 패턴을 확인하는 보조 hook을 함께 넣었습니다. 강제 푸시나 강제 초기화, 넓은 삭제처럼 작업 내용을 잃을 수 있는 명령을 별도로 살피는 구조입니다. 테스트 수정 지시만으로 실행 명령의 경계까지 모두 다뤘다고 보지 않았습니다.

이 hook은 전달받은 명령 문자열을 확인하는 역할입니다. 계획의 목표나 테스트의 의미, 코드의 정확성을 판단하는 장치는 아닙니다. 따라서 명령 확인, 계획 검토, 테스트, 코드 리뷰를 각자의 질문으로 유지합니다.

다음 담당에게는 통과 표시와 함께 무엇을 확인했는지 남깁니다. 수정 담당은 원인과 변경을, 검사 담당은 실행 결과를, 리뷰 담당은 남은 위험을 전달합니다. 그래야 다음 작업에서 다시 확인할 부분을 고를 수 있습니다.