[하네스] 완벽하지 않아도 부분적인 자동화 (클로드 개발-CLI 코덱스 리뷰)

AI 협업 워크플로우

AI 코딩 도구를 함께 쓸 때 작업이 섞이지 않게 관리하는 방법

개인 프로젝트를 AI 코딩 도구와 함께 개발하다 보면 구현, 리뷰, 커밋, 푸시가 한꺼번에 섞이기 쉽다. 이 글은 사용자가 주제를 전달한 뒤, 구현 도구와 리뷰 도구가 어떤 순서로 움직이면 안전한지 정리한 간단한 협업 흐름이다.

1. 이 워크플로우의 목적

핵심 목적은 하나다. 여러 AI 도구가 동시에 구현자로 행동하면서 변경 범위가 커지는 것을 막는 것이다.

구현은 한 곳에서만 진행하고, 다른 도구는 독립 리뷰만 담당하게 한다. 이렇게 하면 코드 수정 범위가 섞이거나, 리뷰 도구가 임의로 파일을 고치는 일을 줄일 수 있다.

• 역할을 명확히 분리한다.
• 구현은 한 도구에서만 진행한다.
• 리뷰 도구는 계획 리뷰와 최종 diff 리뷰만 담당한다.
• 사용자 승인 전에는 커밋과 푸시를 하지 않는다.
• 요구사항 밖 리팩토링이나 설정 변경을 막는다.

2. 전체 흐름 한눈에 보기

내가 쓰기 좋은 형태로 정리하면, AI 협업 개발은 아래 순서로 진행하는 것이 안전하다.

기본 프로세스

01. 사용자 작업 주제와 목표를 전달한다.

→

02. 구현 도구 소스를 1차로 조사하고 수정 계획을 세운다.

→

03. 리뷰 도구 구현 전 계획을 2차로 검토한다.

04. 구현 도구 검토 의견 중 필요한 것만 반영해 개발한다.

→

05. 리뷰 도구 최종 diff를 리뷰해 회귀와 범위 확장을 확인한다.

→

06. 사용자 최종 승인 후 커밋/푸시 여부를 결정한다.

여기서 중요한 점은 리뷰 도구가 파일을 직접 수정하지 않는다는 것이다. 리뷰 도구는 “이 계획이 안전한가?”, “이 diff가 기존 기능을 깨뜨리지 않는가?”를 확인하는 역할에 집중한다.

3. 기본 역할

주체	역할	주의점
사용자	주제 전달, 방향 결정, 최종 승인	커밋/푸시 여부를 명시적으로 결정
구현 도구	소스 조사, 설계, 구현, 최종 반영	리뷰 의견을 검토한 뒤 필요한 것만 반영
리뷰 도구	구현 전 계획 리뷰, 구현 후 diff 리뷰	파일을 직접 수정하지 않음

리뷰 도구의 제안을 자동 반영하지 않는다. 리뷰 의견은 구현 도구가 다시 검토하고, 필요한 것만 최소 변경으로 반영한다.

4. 표준 작업 플로우

표준 흐름은 사용자 주제 전달 → 구현 도구 1차 소스 검토 → 리뷰 도구 2차 검토 → 구현 → 최종 diff 리뷰 → 사용자 승인 순서로 진행한다.

1. 1단계: 사용자가 주제와 목표를 전달 어떤 문제를 해결하려는지, 어떤 화면이나 기능을 바꾸려는지, 커밋/푸시까지 원하는지 또는 로컬 검토만 원하는지 전달한다.
2. 2단계: 구현 도구가 소스 1차 검토 아직 코드를 수정하지 않는다. 요구사항, 관련 파일, 기존 흐름, 수정 대상, 위험 영역, 테스트 항목을 먼저 정리한다.
3. 3단계: 리뷰 도구가 소스/계획 2차 검토 계획이 안전한지, 더 작은 변경으로 가능한지, 기존 기능을 깨뜨릴 가능성이 있는지 확인한다. 이 단계에서도 파일은 수정하지 않는다.
4. 4단계: 구현 도구가 실제 개발 타당한 리뷰 의견만 반영하고, 기존 구조를 유지하면서 필요한 최소 변경만 적용한다.
5. 5단계: 리뷰 도구가 최종 diff 검토 아직 커밋하지 않은 변경분을 기준으로 회귀, 데이터 손실, 모바일/PWA 문제, 중복 구현, 범위 확장을 확인한다.
6. 6단계: 구현 도구가 최종 반영/재검증 필요한 지적만 수정하고 다시 검증한다. 최종 변경 파일, 검증 결과, 남은 리스크를 보고한다.
7. 7단계: 사용자 승인 후 커밋/푸시 사용자가 명시적으로 승인하기 전까지 커밋과 푸시는 하지 않는다.

5. 계획 리뷰에서 볼 것

구현 전 계획 리뷰는 “이 방향으로 가도 안전한가?”를 확인하는 단계다.

범위 요구사항 밖으로 커지지 않는가?

회귀 기존 기능을 깨뜨릴 가능성은 없는가?

안전성 저장, 인증, 세션, 동기화에 부작용은 없는가?

• 더 작은 변경으로 가능한지 확인한다.
• 데이터 손실 위험이 있는지 확인한다.
• 모바일 또는 PWA에서 문제가 생길 수 있는지 확인한다.
• 누락된 테스트가 있는지 확인한다.
• 관련 없는 리팩토링이 섞였는지 확인한다.

6. 최종 diff 리뷰에서 볼 것

최종 diff 리뷰는 구현이 끝난 뒤, 아직 커밋하지 않은 변경분을 보는 단계다. 여기서도 리뷰 도구는 파일을 수정하지 않는다.

기본 확인 명령 예시

git status --short
git diff --name-only
git diff --check

• 기존 기능 파손 여부
• 데이터 손실 위험
• 인증/세션 부작용
• 동기화 버그
• 모바일 UI 또는 PWA 동작 문제
• 업로드, 저장, 삭제 흐름 회귀
• 중복 구현 또는 불필요한 범위 확장
• 에러 처리, fallback, 입력값 검증 누락

7. 다중 세션 작업 시 주의

여러 AI 세션이 같은 프로젝트를 동시에 다루면, 작업 중 git 상태가 바뀔 수 있다. 따라서 시작 전, 커밋 전, 푸시 전 상태 확인이 중요하다.

작업 시작 전 확인

git status -sb
git log --oneline -5

커밋 전 확인

git status --short
git diff --name-only
git diff --cached --name-only

관련 없는 파일이 변경 목록에 보이면 바로 커밋하지 않는다. 먼저 어떤 세션의 작업인지 확인하고, 작업 범위 밖 파일은 stage하지 않는다.

8. 커밋/푸시 원칙

• 사용자 승인 전 커밋/푸시하지 않는다.
• git add ., git add -A는 관련 없는 변경이 있을 때 사용하지 않는다.
• 커밋 대상 파일은 가능하면 path 제한으로 stage한다.
• 푸시 전 변경 파일 목록과 검증 결과를 다시 확인한다.
• 푸시 후에는 커밋 해시, 변경 파일, 검증 결과를 짧게 보고한다.

안전한 stage 예시

git add app.html js/app.js
git diff --cached --name-only

9. 금지사항

• 리뷰 도구가 직접 파일을 수정하게 하지 않는다.
• 두 AI 도구가 동시에 같은 파일을 수정하지 않는다.
• 리뷰 제안을 자동 반영하지 않는다.
• 요구사항 밖 리팩토링을 하지 않는다.
• 저장 구조, 인증, 세션, 동기화, 배포 설정은 명시 승인 없이 변경하지 않는다.
• 파일 삭제는 명시 승인 없이 하지 않는다.
• 테스트 실패를 무시하지 않는다.
• 검증하지 않은 내용을 완료로 보고하지 않는다.

10. UI/디자인 작업은 한 단계 더 나눈다

UI 작업은 구현 전에 디자인 시안 확인 단계를 두는 것이 안전하다.

1. 디자인 요구사항 정리 문제 화면, 참고 이미지, 모바일/PC 제약, 기존 UI 톤을 정리한다.
2. 시안 생성 보통 2~3개 시안을 만들고, 목적과 인상을 다르게 나눈다.
3. 사용자 확정 선택된 시안이 나오기 전까지 실서비스 코드는 수정하지 않는다.
4. 구현 계획 수립 시안 HTML을 그대로 복사하지 않고, 기존 구조에 맞춰 반영 계획을 세운다.
5. 계획 리뷰와 최종 diff 리뷰 모바일 반응형, CSS 전역 영향, 접근성, 더미 코드 잔존 여부를 확인한다.

디자인 시안은 참고자료다. 시안용 HTML/CSS/JS를 검토 없이 운영 코드에 그대로 복사하지 않는다.

11. 한 줄 요약

AI 협업 개발에서 가장 중요한 것은 “사용자 → 구현 도구 → 리뷰 도구 → 구현 도구 → 리뷰 도구 → 사용자 승인”의 흐름을 고정하는 것이다. 역할과 순서를 분리하면 변경 범위가 섞이는 문제를 크게 줄일 수 있다.