처음 읽은 지침을 작업 중에 다시 연결한다
토스뱅크 ML 엔지니어 김경윤은 팀의 코드 관례를 코딩 에이전트가 지키도록 만든 pfmls-stylepack 사례를 공개했다. 원출처는 루트의 지시 문서를 읽어도 세션이 길어지면 규칙을 놓치는 경험이 있었다고 설명한다. 전역 지침에 세부 규칙을 모두 넣기보다 에이전트가 코드와 도구 결과를 주고받는 반복 과정 안에서 관련 규칙을 다시 전달하는 방식을 택했다.
Stylepack은 규칙 하나마다 발동 조건과 전달할 문장을 함께 저장한다. 파일을 작성한 직후 코드 본문과 파일명 패턴을 보고 후보 규칙을 고른다. 팀은 매번 AI로 관련성을 판단했을 때 요청마다 약 10초가 추가됐다고 설명하며 정규식 등 간단한 선택 방식으로 바꿨다. 이 시간은 해당 팀의 관측이며 다른 환경의 성능이나 모든 모델의 행동을 증명한 수치는 아니다.
파일 하나의 피드백과 변경 전체의 검토를 나눈다
작성 직후에는 최대 두 규칙을 전달하고 같은 규칙은 세션당 한 번으로 제한했다. 예시에서는 새 열거형 값의 분기가 빠진 알림 코드를 보고 완전한 분기 처리를 안내했다. 작업 종료 직전에는 전체 git diff를 검토해 최대 네 규칙을 전달한다. 인터페이스와 구현이 각 파일에서는 정상이어도 서비스가 구현체 타입에 묶이는 문제처럼 파일 간 관계를 보기 위한 단계다.
세션 시작에는 pyproject.toml이나 build.gradle을 보고 Python과 Spring에 맞는 공통 지침을 제공한다. 규칙은 서비스 템플릿에 복사해 두지 않고 중앙 저장소에서 받아 갱신하도록 했다. 공식 Claude Code 문서도 도구 실행 후 맥락을 추가하거나 종료 시 피드백으로 작업을 이어가는 훅을 설명한다. 공식 기능은 이런 연결 방식의 근거이며 사내 플러그인의 효과를 독립적으로 검증하는 자료는 아니다.
잘못 뜬 규칙과 빠진 규칙도 기록으로 고친다
팀은 규칙이 언제 어떤 조건으로 발동했는지 파일에 남겼다. 열거형을 딕셔너리 키로 쓰는 형태를 찾던 조건이 다른 코드에도 뜬 사례에서는 21개 세션에서 코드 변경이 없었다고 설명한다. 발동 조건을 다듬어 불필요한 안내를 줄였다. 반대로 반복문 표현을 일부만 찾는 조건은 실제 리뷰에서 발견한 N+1 문제를 놓쳐 공통 지침으로 옮겼다.
반복된 PR 리뷰 의견도 새 규칙의 입력으로 사용했다. 동작과 상태를 가진 클래스를 dataclass로 표현한 지적에서 이름 접미사까지 조건에 넣어 정상적인 값 객체에 과도하게 뜨지 않도록 했다. 규칙 목록을 늘리는 데서 멈추지 않고 발동의 적절성을 다시 살피는 구조다. 원출처는 사례와 개선 과정을 소개했으며 팀 전체의 결함 감소율이나 일반화된 정확도를 발표하지는 않았다.
선택된 지침과 검증된 위반을 구분한다
이 설계에서 정규식은 최종 판정기가 아니라 관련 지침을 전달할 후보를 좁히는 장치다. 그래서 안내가 떴다는 사실만으로 위반이 있다고 볼 수 없고, 코드가 바뀌지 않았다고 곧바로 규칙이 무효라고 볼 수도 없다. 사례를 검토해 발동 이유와 실제 코드의 관계를 확인해야 한다. 적용 기록은 무엇이 자주 보이는지보다 무엇이 도움이 되는지 판단할 자료로 사용할 수 있다.
규칙의 근거가 표준 동작인지 팀 관례인지도 나눌 필요가 있다. 예를 들어 Python 공식 문서는 TaskGroup에서 한 작업이 일반 예외로 실패하면 나머지를 취소하지만 기본 gather는 다른 작업을 계속 실행한다고 설명한다. 어떤 동작이 업무에 맞는지를 팀이 정한 뒤 그 이유를 지침에 담을 수 있다. 특정 API를 항상 바꾸라는 형태보다 필요한 실패 처리 의미를 전달해야 잘못된 적용을 줄인다.
훅이 실제로 관측하는 변경 범위를 확인한다
작성 직후의 빠른 안내와 종료 전 전체 검토는 서로 다른 누락을 다룬다. 다만 훅이 어떤 작업에서 실행되는지도 검토 대상이다. Claude Code 공식 문서는 Edit·Write에 맞춘 PostToolUse 훅이 Bash나 외부 프로세스의 파일 변경에서는 실행되지 않는다고 명시한다. 이를 사내 구현의 결함으로 단정할 수는 없지만, 같은 설계를 도입하는 팀이 확인해야 할 실행 경계다.
중앙 규칙의 갱신도 이미 진행 중인 작업과 새 세션에서 일관되게 보이는지 살펴볼 수 있다. 규칙의 최대 개수는 문맥 부담을 제한하는 선택이며 두 개와 네 개가 모든 팀의 최적값이라는 증거는 아니다. 이 사례의 재사용 가능한 부분은 규칙을 정의하고 필요한 순간에 전달한 뒤 기록으로 개선하는 흐름이다. 실제 적용 범위와 효과는 해당 코드베이스의 리뷰와 검증 결과로 판단해야 한다.
출처
토스테크의 원출처와 본문에 표시한 참고자료를 바탕으로 한국어로 재구성했습니다. ‘ARCH.B 분석’은 자료를 읽고 덧붙인 편집 해석입니다.
AI가 팀 규칙을 지키도록 하는 방법 (새 창)
