SI Harness — AI 협업 SI 워크플로우 자동화

프로젝트 배경

화면을 만드는 프로젝트가 아니라, 화면을 만드는 과정을 AI가 따라올 수 있게 만든 작업 환경입니다. Claude Code용 command·skill·agent·hook·status 파일을 묶어, SI 프로젝트에서 반복되는 흐름을 저장소에 고정했습니다.

담당 범위

• 제안~인수 6단계 파이프라인(/si-proposal → kickoff → design → dev → deploy → handoff)
• 횡단 흐름(/si-cr 변경 요청, /si-hotfix 긴급 수정, /si-status 상태 조회)
• 역할별 agent(architect·entity-dev·ui-dev·test-eng·reviewer·devops) 위임 구조
• Global Layer / Project Layer 분리 및 프로젝트 템플릿(.claude·.si)
• 세션 시작·컨텍스트 압축 전 상태 보존 hook

문제 정의

• 매번 다시 쓰는 작업 기준 — '지금은 요구사항 단계다', 'API 확정 전이다', '화면보다 엔티티 먼저다' 같은 기준을 세션마다 프롬프트에 다시 써야 했습니다.
• 컨텍스트 압축에 휘발되는 합의 — 대화가 길어져 컨텍스트가 압축되면, 합의했던 순서가 대화 안에서만 존재하다 사라졌습니다.
• 한 덩어리로 뭉치는 작업 — '주문 목록 만들어줘' 한마디에 타입·API·UI·검증이 한꺼번에 섞여, 문제가 나도 어느 층에서 깨졌는지 추적할 수 없었습니다.
• AI의 API 상상 — 스펙이 없으면 AI가 그럴듯한 경로를 지어내, 실제 백엔드와 어긋나는 코드를 만들었습니다.

기술적 의사결정

1. 작업 순서를 command·skill로 고정

• 배경 — 순서를 프롬프트로만 유지하면 세션마다 흔들립니다.
• 선택 — 제안·착수·설계·구현·배포·인수를 각각 command 또는 skill로 나누고, SI 특성상 상시 발생하는 변경 요청·긴급 수정·상태 조회를 횡단 흐름으로 따로 뒀습니다. 예외를 '수정해줘' 한마디로 뭉뚱그리지 않도록 흐름을 명시했습니다.
• 트레이드오프 — 흐름을 고정하면 자유도는 줄지만 재현성이 올라갑니다. SI처럼 같은 절차가 반복되는 일에서는 자유도보다 재현성이 이득이라 판단했습니다.

2. 구현을 역할별 agent에 위임

• 배경 — 한 프롬프트가 여러 관심사를 동시에 처리하면 원인 추적이 불가능합니다.
• 선택 — 데이터 레이어(entity-dev)와 화면 레이어(ui-dev)를 나누고 검증(test-eng·reviewer)을 분리해, 문제가 났을 때 원인을 레이어 단위로 좁힐 수 있게 했습니다.

3. 진행 상태를 status.json에 단일 원천으로 보존

• 배경 — 세션이 바뀌거나 컨텍스트가 끊기면 진행 맥락이 사라집니다.
• 선택 — 현재 phase·phase 이력·변경 요청·gate 통과 여부를 파일로 관리하고, 세션 시작·컨텍스트 압축 전 hook으로 현재 상태를 출력해, 대화가 끊겨도 다시 이어갈 기준을 만들었습니다.

4. 설계 단계에서 API를 상상하지 않게 강제

• 배경 — AI가 지어낸 API는 실제 스펙과 어긋난 코드로 이어집니다.
• 선택 — Swagger·백엔드 문서가 있으면 그것을 기준으로 정리하고, 없으면 '없음'으로 표시해 백엔드 요청 사항으로 남겼습니다. 모름을 모름으로 남기게 해 환각을 막았습니다.

결과

• 제안~인수 6단계 + 횡단 3흐름을 command·skill로 고정해 세션 간 재현성 확보
• 구현을 데이터/화면/검증 역할별 agent로 분리해 원인 추적성 확보
• status.json + hook으로 세션·컨텍스트가 끊겨도 진행 상태 복원
• Global/Project 레이어 분리로 새 SI 프로젝트에 작업 환경을 빠르게 이식
• 설계 단계 '확인·미확인 명시' 원칙으로 API 환각 차단

회고

AI와 오래 일할수록, 좋은 결과는 좋은 프롬프트가 아니라 좋은 제약에서 나온다는 생각이 굳어졌습니다. 순서·역할·상태를 대화에 맡기지 않고 저장소(command·agent·status.json)에 고정하니, 세션이 끊겨도 같은 품질로 이어졌습니다. 특히 "모르는 API는 지어내지 말고 '없음'으로 남긴다"는 규칙 하나가 환각을 크게 줄이는 걸 보며, AI에게 자유를 주는 것보다 경계를 명확히 하는 것이 실무에서 더 강력하다는 원칙을 얻었습니다. 프론트엔드 실무의 반복 절차를 구조로 환원해 본 경험은, 제품 코드에서 "무엇을 고정하고 무엇을 열어 둘지"를 판단하는 감각과도 이어졌습니다.