Coding Workflow Design
이 문서는 CCAF Domain 3를 이해하기 위한 개념 설명용 노트다.
여기서는 실행 전 제어보다, 읽기·계획·수정·검증·검토를 어떤 반복 가능한 작업 루프로 만들 것인가를 다룬다. 즉 coding workflow를 단순한 작업 순서가 아니라, Claude Code가 반복적으로 안정적인 결과를 내도록 만드는 workflow loop 설계로 이해하는 데 초점을 둔다.
왜 workflow design이 중요한가
Claude Code를 잘 쓴다는 것은 한 번 멋지게 수정하는 능력만을 뜻하지 않는다.
실제로 더 중요한 것은:
- 낯선 코드베이스를 어떻게 읽고
- 어떻게 작업 범위를 잡고
- 어떤 단위로 수정하고
- 무엇으로 검증하고
- 어떤 기준으로 다시 점검하는가
를 반복 가능한 방식으로 굴리는 것이다.
즉 coding workflow의 핵심은 단순 생산성이 아니라,
반복 가능한 안정성(repeatable reliability)
이다.
좋은 workflow는 어떤 루프를 가지는가
작업마다 다르지만, 보통 좋은 coding workflow는 아래 흐름을 가진다.
- 읽기 / 탐색
- 관련 파일, 구조, 의존성 파악
- 계획 (Plan Mode)
- 수정 전략과 영향 범위 정리
- 수정
- 작은 단위 또는 의도된 단위로 변경
- 검증
- 테스트, lint, typecheck, 수동 확인 (CI Guardrails와 연결)
- 검토
- diff 확인, 요구사항 재대조, 누락 점검
즉 workflow는 선형 체크리스트가 아니라,
읽기 → 계획 → 수정 → 검증 → 검토의 반복 루프
로 보는 편이 좋다.
작은 작업과 큰 작업의 workflow는 어떻게 다른가
모든 작업이 같은 workflow를 필요로 하지는 않는다.
작은 작업
- 관련 파일 수가 적다
- 변경 의도가 분명하다
- 검증이 단순하다
- 한 번의 수정 루프로 끝나기 쉽다
예:
- 문구 수정
- 단순 버그 fix
- 명백한 타입 에러 수정
큰 작업
- 영향 범위가 넓다
- 여러 파일이나 계층이 연결된다 (Task Decomposition이 중요)
- 요구사항 해석이 필요하다
- 검증 루프가 길다
- 중간 점검이 필요하다
예:
- 리팩터링
- 새 기능 추가
- 테스트 체계 재구성
- 구조 변경
즉 workflow 설계의 핵심은 하나의 정답을 강요하는 것이 아니라,
작업 크기와 위험에 따라 루프의 밀도를 조절하는 것
이다.
왜 작은 단위의 수정이 중요한가
Claude Code가 한 번에 큰 변경을 만들 수는 있다.
하지만 큰 수정은 종종:
- 원인 파악을 어렵게 만들고
- diff 검토를 힘들게 하고
- 실패 시 되돌리기 어렵고
- 검증 범위를 넓힌다
반대로 작은 단위의 수정은:
- 의도를 더 분명하게 보여주고
- 문제가 생겼을 때 위치를 좁히고
- 테스트와 검토를 더 쉽게 만든다
즉 workflow 관점에서 작은 수정은 단순 취향이 아니라,
복구 가능성과 검토 가능성을 높이는 전략
이다.
검증은 workflow의 마지막 장식이 아니다
많은 사람이 수정 후 테스트를 “있으면 좋은 마지막 단계”처럼 본다.
하지만 좋은 workflow에서 검증은 부록이 아니다.
검증은:
- 변경이 실제로 맞는지 확인하고
- 예상 못 한 영향 범위를 드러내고
- 계획과 실행의 어긋남을 발견하게 하고
- 다음 반복 루프로 되돌아갈지, 종료할지 판단하게 한다
즉 테스트, lint, typecheck, 수동 확인은 단순 체크박스가 아니라,
작업 루프의 방향을 교정하고 종료 여부를 판단하게 만드는 단계
다.
왜 이게 harness engineering과 연결되는가
좋은 하니스는 모델이 코드를 “생성”하게만 두지 않는다.
그보다:
- 읽는 단계가 있고
- 수정 단위를 조절하고
- 검증을 삽입하고 (Hooks로 자동화 가능)
- 검토와 반복을 가능하게 한다
즉 coding workflow design은 사실상
Claude Code가 어떤 반복 작업 루프 안에서 움직이게 할 것인가를 설계하는 일
이다.
그래서 workflow는 단순 습관이 아니라, 운영 가능한 coding harness의 핵심 구조가 된다.
흔한 오해
“좋은 모델이면 workflow는 대충이어도 된다”
아니다. 모델 품질이 높아도 작업 루프가 불안정하면 결과도 흔들린다.
“검증은 마지막에 한 번만 하면 된다”
그렇지 않다. 큰 작업일수록 중간 검증과 단계적 확인이 중요하다.
“큰 작업일수록 한 번에 크게 수정하는 게 효율적이다”
겉보기엔 빨라 보여도, 검토와 복구 비용이 커질 수 있다.
한 문장 요약
Coding workflow design은 Claude Code가 한 번 잘 작동하게 만드는 것이 아니라, 읽기·계획·수정·검증·검토를 반복 가능한 workflow loop로 만들도록 설계하는 일이다.