반복 규칙과 구현 판단을 나누기
HASHI는 한국인 여행객을 위한 일본 맛집 큐레이션·예약 요청 서비스입니다. 예약·포인트 API를 연결하는 프론트엔드 개발과 함께, AI가 팀의 개발 기준을 참조할 수 있도록 저장소 문서와 실행 지침을 구성했습니다.
페이지와 공용 컴포넌트에는 코드 외에도 명세, 상태별 사용 예시, 공개 export가 필요했습니다. 반복되는 파일 구성은 생성기에 반영하고, API 응답이나 화면 흐름에 따라 달라지는 판단은 별도의 지침으로 정리했습니다.
고정된 파일 구성은 생성기로
팀원이 만든 기존 Turbo generator를 확장했습니다. 페이지에는 코드·명세·index를, 디자인시스템 컴포넌트에는 코드·명세·Storybook·공개 export를 함께 생성하고 포맷을 적용하도록 구성했습니다.
- 페이지·컴포넌트 이름생성 대상 입력
- 정해진 템플릿경로·파일 구성 적용
- 코드와 검토 자료명세 / HDS Storybook / export
- 내용 작성·검증작업별 요구사항과 동작 확인
반복되는 구조를 매번 새로 생성하도록 맡기는 대신 코드에 담았습니다. 컴포넌트의 역할, 필요한 상태와 접근성 동작은 해당 작업에서 채우고 검토해야 합니다.
명세 해석과 구현과 검증을 분리
사람이 읽는 팀 규칙은 docs/에, AI가 작업할 때 따를 순서와 확인 기준은 .agents/에 두었습니다. 작업 유형에 따라 필요한 문서를 찾도록 루트 지침을 구성하고, API 작업은 명세 해석·구현·검증 단계로 나눴습니다.
| 단계 | 확인할 내용 | 다음 단계의 입력 |
|---|---|---|
| 명세 해석 | 요청·응답, 화면 상태, 누락 정보 | API Integration Map |
| 구현 | API와 화면 연결, 캐시 갱신, 오류 상태 | 구현 코드와 갱신된 화면 명세 |
| 검증 | 계층 경계, query key, 상태 처리, 테스트 | 확인 결과와 남은 항목 |
필수 구현 정보가 없으면 먼저 확인을 요청하도록 명세 해석 지침에 적었습니다. 이는 에이전트가 따라야 할 절차이며, 모든 단계 전환을 별도 런타임이 자동으로 강제하는 구조는 아닙니다.
예약 구현에서 얻은 기준을 다음 작업에 반영
예약 생성 응답은 완전한 예약 상세 객체나 최신 포인트 잔액을 모두 보장하지 않았습니다. 응답에 없는 값을 추측해서 캐시에 채우지 않고, 필요한 데이터를 서버에서 다시 조회하도록 구현했습니다.
PR #94에서는 이 작업과 함께 기존의 단순한 캐시 무효화 지침을 조건별 선택표로 확장했습니다. 팀 문서와 AI 스킬 양쪽을 갱신해 같은 기준을 참조하도록 했습니다.
| 확인한 조건 | 지침에 반영한 처리 |
|---|---|
| 완전한 최신 객체를 같은 화면에 즉시 반영 | 해당 상세 캐시를 직접 갱신 |
| 부분 응답이거나 화면 이동·목록·집계 변화가 있음 | 관련 캐시를 무효화하고 서버에서 재조회 |
| 상세 즉시 반영과 목록 갱신이 모두 필요 | 직접 갱신과 재조회 조합 |
규칙을 많이 만드는 것보다, 실제 기능을 구현하면서 확인한 조건을 다음 작업의 기준에 반영하는 데 의미가 있었습니다.
구현과 검증
기존 Turbo generator에 페이지·HDS 명세와 Storybook·export 생성을 더하고, API 작업별 지침과 필수 경로 검사 스크립트를 구성했습니다. 2026.09.21에는 필수 경로 검사를 로컬에서 실행해 필요한 파일이 갖춰졌는지 확인했습니다.
필수 경로 검사는 파일 누락을 찾는 용도입니다. 내용의 정확성은 작업별 리뷰와 저장소의 lint·typecheck·test·build로 따로 확인해야 합니다. 이 사례에서 구현한 범위는 생성기와 작업 지침이며, 에이전트의 병렬 실행·자동 재시도를 제어하는 런타임은 포함하지 않습니다.
이 경험을 바탕으로 갖게 된 AI 설계 관점
새로운 AI 도구나 개발 방식이 나오면, 어떤 문제를 해결하려는 것인지부터 살펴봅니다. 하네스나 그래프라는 이름보다 어디에 모델의 판단이 필요하고, 무엇을 코드로 고정해야 하는지가 중요하다고 생각합니다.
HASHI에서는 반복되는 파일 구성은 생성기로 만들고, API 작업은 명세 해석·구현·검증으로 나눴습니다. 실제 예약 기능을 개발하면서 정리한 캐시 처리 기준도 AI 지침에 반영했습니다.
이 경험을 바탕으로, AI가 일을 수행하는 경로뿐 아니라 결과를 받아들일 기준과 실패했을 때의 다음 행동까지 함께 설계하려 합니다. 다시 실행하면 되는 오류인지, 입력을 보완해야 하는지, 사람의 결정이 필요한지를 구분하는 데 관심이 있습니다.
| 대상 | 판단 기준 |
|---|---|
| 사람의 판단 | 문제·우선순위·허용 위험·미확정 요구사항 |
| 코드 검증 | 형식·필수 항목·타입·중복·테스트 조건 |
| 실패 후 행동 | 원인에 따라 제한적 재시도, 입력 보완, 사람의 결정 요청 |
이는 현재의 관점과 후속 설계 방향입니다. 코드 검사를 통과한 것과 고객에게 적합한 결과인지는 다르게 확인해야 하며, AI를 항상 같은 답을 내는 시스템으로 만들었다는 뜻은 아닙니다.