매 턴 전체 검사 대신 변경한 영역부터 확인하기

턴이 끝날 때마다 서버와 클라이언트 전체를 고쳤다

AI Commons의 이전 Claude Stop hook은 매 턴 종료 때 server와 client에서 npm run fix와 typecheck를 차례로 실행했다. fix는 린트와 포맷을 수정하는 명령이다. 설명만 마친 턴이나 작은 변경에도 두 영역을 대상으로 파일 수정과 전체 검사가 이어지는 구조였다.

턴이 끝났다는 신호는 하나의 코드 변경이 완성됐다는 신호와 다르다. 이 스크립트는 검사 결과 뒤에도 무조건 exit 0으로 끝났다. hook이 성공으로 종료했다는 사실만으로 앞선 타입 검사가 통과했다고 판단할 수도 없었다. 실행 시점과 성공 신호가 코드 품질을 확인할 경계에 맞지 않았다.

검사를 없애는 대신 코드 수정 완료에 연결한다

변경은 settings의 Stop 등록과 자동 수정 스크립트를 제거하고 AGENTS.md에 작업 후 검사 규칙을 추가했다. 코드를 수정한 뒤 변경 영역의 린트·포맷·타입 검사를 수행하고, 린트와 포맷은 변경 파일을 우선 검사한다. 전체 검사는 필요할 때 순차 실행하도록 범위를 옮겼다.

변경 파일만 보는 것으로 충분하다는 규칙은 아니다. 공유 타입이나 설정을 바꾸면 영향받는 영역의 타입 검사와 더 넓은 확인이 필요하다. 대신 대화 턴 수에 따라 반복 실행되던 검사를 변경 내용과 영향 범위에 따라 선택한다. 자동 수정 명령을 썼다면 그 명령이 만든 변경도 함께 검토해야 한다.

자동 실행을 줄이면 검사 선택의 책임이 커진다

항상 실행되는 hook을 없애면 agent가 필요한 검사를 빠뜨릴 가능성을 별도로 다뤄야 한다. 작업 완료 보고에는 무엇을 검사했는지, 실패나 미확인 범위가 있는지 남겨야 한다. 전체 검사를 덜 한다는 사실이 품질 향상이나 시간 절감을 자동으로 증명하지는 않는다.

이 저장소의 AGENTS.md는 아키텍처·프런트엔드·백엔드·테스트 같은 작업별 문서 경로도 안내하고 CLAUDE.md에서 불러온다. 관련 문서를 찾는 경로와 변경 뒤 검사 규칙을 함께 두면 다음 행동의 근거를 찾기 쉽다. 다만 이 문서 연결만으로 모든 모듈의 지침이나 실제 agent의 준수 여부까지 확인되는 것은 아니다.

변경에서 확인할 수 있는 결과는 Stop 등록과 스크립트의 제거, 그리고 변경 영역을 우선 검사하는 지침의 추가다. 이후 모든 작업의 준수율이나 생산성 수치는 없다. Xinics Skill Plugin에서 다루는 에이전트 작업 지침과 연결되는 이 사례는, 실제 AI Commons 저장소에서 검사 시점을 대화 종료에서 코드 변경 완료로 옮긴 구체적인 작업 규칙이다.