인공지능 프로그래밍 에이전트를 대상으로 하는 지침 파일은 끝없이 확장할 것이 아니라 지속적으로 검토해야 한다. 모델이 실수할 때마다 새로운 규칙이 추가되고, 도구가 바뀔 때마다 우회 방법이 추가되는 한편, 최신 모델이 등장한 뒤에도 이전 모델을 위한 지침은 그대로 남는다. 그 결과 하나의 파일이 개발자 설정 가이드, 스타일 가이드, 문제 해결 기록, 오래된 프롬프트 작성 기법 모음의 성격을 동시에 띨 수 있다.
이 글에 따르면 이러한 누적은 프로그래밍 에이전트의 효율을 떨어뜨릴 수 있다. 최신 모델은 저장소를 탐색하고, 일반적인 프레임워크를 식별하며, 기존 패턴을 따르고, 흔한 오류를 처리하는 능력이 향상되었다. 그러나 팀의 고유한 결정, 숨은 제약 조건, 팀 내부에 축적된 운영 경험은 알지 못한다. 따라서 목표는 지침 파일을 가능한 한 짧게 만드는 것이 아니라, 결과를 실제로 바꾸는 고신호 정보 중 가장 작은 집합을 유지하는 것이다.
컨텍스트를 제한된 자원으로 다루기
지침 파일은 적용되는 모든 요청에서 모델이 사용할 수 있는 컨텍스트에 추가되며, 그 안의 각 줄은 개발자의 작업, 관련 코드, 도구 출력, 대화 기록, 기타 지침과 모델의 주의를 놓고 경쟁한다. 컨텍스트 창이 넓다고 해서 추가되는 모든 토큰에 비용이 없는 것은 아니다.
실질적인 질문은 ‘저장소에 관해 모델에게 무엇을 알려줄 수 있는가?’가 아니다. ‘모델이 알아야 하지만 안정적으로 발견하거나 추론하거나 검색할 수 없는 것은 무엇인가?’가 되어야 한다. 이 글은 구체적이고 영향력이 있으며 추론하기 어려운 정보에 집중할 것을 권한다.
파일에 남겨야 할 내용
가치가 가장 높은 정보에는 시스템에 관한 명확하지 않은 사실이 포함된다. 예를 들어 저장소 구성 요소 간 소유권의 경계, 오래된 디렉터리가 여전히 프로덕션에서 사용된다는 사실, 특정 파일이 생성된 파일이어서 수동으로 수정해서는 안 된다는 사실 등이 있다. 특정 인터페이스가 공개 HTTP 계약을 소유한다거나, 도메인 규칙이 특정 계층에 속한다는 점을 명시하는 것이 유용하다. 모델이 디렉터리 이름만 보고 이러한 경계를 추론하도록 두는 것보다 낫다.
검증된 명령만 포함하여 빌드와 검증을 수행하는 가장 짧고 신뢰할 수 있는 경로도 문서화해야 한다. 이 글의 예로는 첫 번째 빌드 전에 dotnet restore App.slnx를 실행한 다음 dotnet build App.slnx --no-restore를 사용하고, API를 변경할 때 특정 테스트를 실행하거나 계약을 수정한 뒤 생성된 파일 검증 도구를 실행하는 방법이 제시된다. 통합 테스트에는 Docker가 필요하고 병렬로 실행해서는 안 되는 것처럼 특별한 요구 사항도 명시해야 한다. 잘못된 명령을 자신 있게 반복하는 것은 명령이 아예 없는 것보다 나쁘기 때문이다.
코드만으로 일관되게 결정할 수 없는 로컬 선택 사항도 기록하는 것이 유용하다. 예를 들어 사용하는 테스트 프레임워크, 컨트롤러보다 Minimal APIs를 선호하는 방식, 예상되는 도메인 오류를 처리할 때 Result<T> 패턴을 사용하는 방식, 시스템 시계를 직접 호출하는 대신 TimeProvider를 사용하는 방식 등이 있다. 이는 일반적인 프로그래밍 규칙이 아니라 코드베이스에 특화된 결정이므로 지침 파일에 적합하다.
엄격한 제약 조건에는 실제로 절대적인 규칙에만 ‘항상’, ‘절대’, ‘반드시’와 같은 표현을 사용해야 한다. 예를 들어 공개 JSON 계약을 유지할 것, 고객 데이터를 로그에 기록하지 않을 것, 데이터베이스 마이그레이션을 이전 버전과 호환되게 만들 것, 명시적인 배포 작업 없이 프로덕션 환경 파일을 수정하지 않을 것 등이 이에 해당한다. 또한 인터페이스 설계 지침 파일, 런타임 버전 지정 파일, 배포 문서, 아키텍처 결정 기록처럼 내용을 복사하기보다 단일 진실 공급원을 가리킬 수도 있다.
삭제하거나 옮길 수 있는 내용
이 글은 깨끗한 코드를 작성하라, 모범 사례를 따르라, 의미 있는 이름을 사용하라, 오류를 적절히 처리하라와 같은 일반적인 조언을 삭제할 것을 권한다. 이러한 표현은 실제 결정을 확정하지 못한다. 반면 기존 ProblemDetails 도구를 사용해 검증 오류는 400 응답에, 존재하지 않는 리소스는 404 응답에, 동시성 충돌은 409 응답에 매핑하라는 식의 구체적인 로컬 규칙이 더 유용하다.
일반적으로 파일에 디렉터리의 전체 목록을 포함할 필요도 없다. 모델은 저장소 구조를 빠르게 읽을 수 있기 때문이다. 도구가 강제하는 서식 규칙을 반복할 필요도 없으며, dotnet format --verify-no-changes와 같은 적절한 검증 명령만 언급하면 된다. 유지 관리 비용이 증가하거나 문서 간 불일치가 생기지 않도록 README, 아키텍처 가이드, 기여 가이드를 통째로 복사하는 것도 피해야 한다.
이 글은 또한 오래된 ‘프롬프트 신화’를 경고한다. 예를 들어 모델에게 심호흡을 하라고 하거나, 고위급 엔지니어처럼 행동하라고 하거나, 변경을 수행하기 전에 모든 파일을 읽으라고 요구하는 방식이다. 이러한 표현은 프로젝트에 관한 지식을 추가하지 않으며 불필요한 탐색을 초래할 수 있다. 대신 결과, 제약 조건, 필요한 검증을 설명하는 것이 낫다. 즉 근본 원인을 해결하는 최소한의 변경을 수행하고, 공개 동작을 유지하며, 대상 테스트를 실행하도록 하는 것이다.
임시 해결책은 그것을 필요로 했던 문제가 해결된 뒤 삭제해야 한다. 그렇지 않으면 에이전트는 더 이상 고장 나지 않은 경로를 계속 피하게 된다. 또한 지침은 특정 버전이 아니라 모델 계열에 맞게 작성해야 한다. 모델별 경로로 나뉘는 지침은 모델과 그 동작이 변화할 때 취약해지기 때문이다.
지침의 범위 선택과 검토
모든 지침이 저장소 전체 파일에 적합한 것은 아니다. GitHub Copilot은 .github/copilot-instructions.md의 전역 지침, .github/instructions/ 아래의 경로별 파일, 그리고 AGENTS.md와 같은 에이전트 지침을 지원한다. 두 파일이 모두 존재하면 전역 지침 파일은 일치하는 경로별 파일과 함께 사용된다.
시스템 구조, 공통 명령, 전역 제약 조건은 전역 범위에 두고, 프레임워크 규칙, 테스트 패턴, 특정 부분에 해당하는 생성 파일 규칙은 경로별 파일로 옮겨야 한다. 세부 설명, 결정의 역사, 드문 절차는 관련 문서에 남겨두는 것이 좋다. 이렇게 하면 React 구성 요소 테스트에 관한 규칙이 데이터베이스 마이그레이션 작업 중인 모델의 주의를 소모하지 않는다.
이 글은 각 지침을 네 가지 결과에 따라 검토할 것을 제안한다. 유지는 해당 지침이 정확하고 영향력이 있으며 추론하기 어려울 때 선택한다. 삭제는 모델이 알고 있거나 도구가 강제하거나, 모호해졌거나 오래된 경우에 선택한다. 이동은 유용하지만 다른 경로나 문서에 속할 때 선택한다. 검증은 명령, 임시 해결책, 또는 변경되었을 가능성이 있는 버전에 관한 내용일 때 선택한다.
검토 시점에는 더 유능한 모델을 도입했을 때, 빌드 시스템을 변경했을 때, 저장소를 재구성했을 때, 또는 에이전트가 지침을 무시하거나 잘못 적용하는 것이 관찰되었을 때가 포함된다. 그 후 더 작은 파일을 특정 작업에 적용해 테스트하고, 실제 실패 사례를 기록한 다음, 재발을 막는 데 필요한 최소한의 지침을 추가하고 다른 작업에서 다시 테스트한다.
프로젝트 유지 관리의 일부
이 글은 일반적인 풀 리퀘스트에서 지침 파일의 변경 사항을 검토하고, 해당 규칙이 재사용 가능한지 아니면 단 하나의 작업만 처리하는지 검토자에게 질문하며, 운영 명령과 환경 요구 사항의 담당자를 지정할 것을 권한다. 또한 문제의 원인을 해결하는 풀 리퀘스트에서 임시 해결책을 삭제하고, SDK 패키지, 프레임워크, 테스트 도구 또는 빌드 경로를 업데이트한 뒤 명령을 다시 확인해야 한다.
파일의 품질을 줄 수로 측정해서는 안 된다. 30줄로 이루어진 파일에 잘못된 명령이 포함되어 있는 경우, 다중 프로젝트 저장소의 경계와 모델이 추론할 수 없는 정보를 설명하는 100줄짜리 파일보다 더 나쁠 수 있다. 더 나은 기준은 파일이 유능한 모델이 신속하게 작업을 시작할 수 있도록 하는지 여부다. 이를 위해 팀만 알고 있는 다음 정보를 제공해야 한다: 시스템이 무엇인지, 중요한 경계, 로컬 선택 사항, 빌드 및 검증 방법, 절대로 망가뜨려서는 안 되는 것, 더 깊이 있는 세부 정보를 찾을 수 있는 위치.