Claude Code, Cursor, 또는 Copilot에서 프로젝트를 열고 첫 번째 프롬프트(prompt)를 입력해 보세요.

여러분의 요청이 모델(model)에 도달하기도 전에, 도구는 이미 CLAUDE.md, AGENTS.md, .cursorrules, Copilot 지침(instructions), 가져온 규칙 파일(rule files), 그리고 여기저기 흩어진 프로젝트 노트들을 로드했을 수도 있습니다.

따라서 에이전트(agent)에게 무엇을 할지 말하기 전에, 저장소(repository)는 이미 에이전트에게 어떻게 행동해야 하는지를 말해준 상태입니다. 이는 보통 괜찮습니다. 이러한 도구들이 작동하도록 설계된 방식이기 때문입니다.

...하지만 이는 지침 계층(instruction layer)을 설정해 두고 잊어버리기 쉽게 만들기도 합니다. 그 보이지 않는 컨텍스트(context)는 수천 개의 토큰(tokens)에 달할 수 있으며, 방금 여러분이 입력한 메시지에는 전혀 나타나지 않습니다.

그래서 에이전트가 규칙을 무시한다면, 당연한 결론은 모델이 실패했다는 것입니다. 하지만 만약 그 규칙이 수천 개의 토큰에 달하는 지침 아래에 파묻혀 있다면 어떨까요? 혹은 동일한 정책이 세 가지 서로 다른 도구를 위해 세 개의 파일에 존재하고, 그 복사본들이 더 이상 일치하지 않는다면 어떨까요?

저는 실제 프로젝트에서 그 보이지 않는 계층이 얼마나 커졌는지 알고 싶었습니다. 그래서 100개의 인기 있는 오픈 소스 저장소(open-source repositories)를 스캔했습니다.

72개는 AI 지침 파일(AI instruction files)을 가지고 있었습니다. 채택된 저장소의 중앙값(median)은 저장소에 구성된 AI 도구 전반에 걸쳐 항상 로드되는 지침이 2,269 토큰에 달했습니다. 하나는 29,000 토큰 이상을 포함하고 있었습니다.

하지만 가장 흥미로운 숫자는 가장 큰 파일이 아니었습니다. 여러 개의 지침 파일을 가진 54개의 저장소 중, 28개는 파일 간에 규칙이 중복되어 있었습니다.

보이지 않는 프롬프트(prompt)는 단순히 커지기만 하는 것이 아니었습니다. 그것은 분기(forking)되고 있었습니다.

우리가 거의 차이점(diff)을 확인하지 않는 계층

AI 지침 파일은 행동 설정(behavioral configuration)입니다. 이는 에이전트가 코드를 작성하고, 테스트를 실행하고, 커밋(commits)을 구조화하고, 파일 이름을 지정하는 방식을 변경합니다. 이 파일들은 Git에 존재하지만, 우리는 주변 코드에 부여하는 것만큼의 규율을 이들에게 부여하는 경우가 거의 없습니다. 크기 예산(size budget)도 없고, 규칙 변경을 행동 변경으로 취급하는 리뷰(review)도 없으며, 복사본들이 일치하는지 확인하는 체크(check)도 없습니다.

이들은 한 번에 한 섹션씩 성장합니다. 규칙들은 도구들 사이에서 복사됩니다. 오래된 가이드는 그것을 유발했던 프로젝트의 결정보다 더 오래 살아남습니다. 그리고 이는 여러분에게 두 배의 비용을 치르게 합니다:

• 컨텍스트 (Context). 항상 로드되는 지침(instructions)은 여러분의 작업, 코드, 또는 에러 출력(error output)이 도착하기도 전에 유효한 컨텍스트 (context)의 일부를 차지합니다.
• 어텐션 (Attention). 가장 중요한 단 하나의 규칙이 수천 개의 다른 지침 및 상용구 (boilerplate) 토큰들과 경쟁해야 합니다.

그리고 이 모든 과정은 보이지 않습니다. 대부분의 사람들은 자신의 설정 레이어 (config layer)를 단일 숫자로 확인해 본 적이 없습니다.

100개의 실제 리포지토리(repos) 현황

저는 **100개의 유명한 오픈 소스 프로젝트 (open-source projects)**의 AI 설정에 대해 린터 (linter)를 실행했습니다. 이 목록은 AI 네이티브 도구 (AI-native tooling, SDK, 에이전트 (agents), 프레임워크 (frameworks))에 의도적으로 치우치도록 선별된 목록입니다. 이를 GitHub의 무작위 샘플이 아니라,

숫자가 의미하는 것 (그리고 의미하지 않는 것)

이 발자국(footprint) 수치는 항상 로드되는 규칙(always-loaded rules)만을 집계합니다. 특정 경로에서만 도구가 첨부하거나 필요할 때 불러오는(on demand) 파일들은 제외했습니다. 그렇기 때문에 34개의 지침(instruction) 파일을 가진 microsoft/vscode는, 제공되는 모든 파일을 합쳤을 때 얻을 수 있는 약 30,000개의 토큰이 아니라, 항상 켜져 있는(always-on) 약 2,600개의 토큰만을 기여합니다.

결합된 발자국(combined footprint)은 또한 저장소(repository)에서 감지된 서로 다른 AI 도구들의 설정(configurations)을 합산합니다. Claude Code는 Claude의 적용 가능한 지침을 로드하고, Cursor는 Cursor의 지침을 로드합니다. 총합은 하나의 어시스턴트가 단일 요청에서 반드시 읽는 양이 아니라, 해당 저장소가 도구 전반에 걸쳐 얼마나 많은 항상 켜져 있는 AI 정책(always-on AI policy)을 유지하고 있는지를 보여줍니다.

여러 개의 지침 파일이 있는 것이 자동으로 문제가 되는 것은 아니지만, 이는 동일한 가이드라인이 도구 간에 복사될 기회를 만듭니다. 실제 사례로, documenso는 .cursorrules와 AGENTS.md 양쪽 모두에 코딩 규칙 블록을 유지하고 있습니다: 네 개는 정확히 중복되며, 두 개는 거의 일치합니다. 두 파일에 있는 하나의 동일한 규칙은 다음과 같습니다: "1줄짜리 if 문을 절대 사용하지 마세요." 현재로서는 해롭지 않습니다. 하지만 이제 이 정책은 두 개의 진실의 원천(sources of truth)을 갖게 되었습니다. 누군가 한 파일의 규칙을 수정하고 다른 파일은 잊어버리는 날에는, 아무도 모르게 복사본들이 서로 달라질 수 있습니다. 세 개의 도구를 위해 병렬로 유지되는 250줄짜리 파일에서 이런 일이 발생한다고 가정하면, 드리프트(drift, 괴리)는 더 이상 가설이 아닙니다.

documenso's .cursorrules and AGENTS.md share four identical rules and two near-duplicates. Two sources of truth for the same policy.

또한 저는 MCP 오버헤드(overhead)를 제외했는데, 이는 의미 있는 컨텍스트 비용(context cost)이 정적 설정 파일(static config file) 자체가 아니라 런타임 도구 스키마(runtime tool schemas)에서 발생하기 때문입니다.

내가 만든 것

저는 린터(linter)를 작은 VS Code 확장 프로그램인 ContextGuard로 변환했습니다. 이 도구는 우리가 코드에서 이미 기대하고 있는 가시성(visibility)을 이 계층에 제공합니다:

• 결합된 지시문 발자국(instruction footprint, 도구 전체에 걸쳐 항상 로드되는 토큰의 합계)을 보여주는 **상태 표시줄 카운터 (status-bar counter)**와 마우스 호버 시 예상되는 월간 비용.
• 감지된 지시문 컨텍스트(instruction context)의 미리보기 (preview). 로드 순서대로 표시되며, 임포트(import)가 확장되고, 항상 로드되는 규칙(always-loaded rules)과 범위 지정/온디맨드(scoped/on-demand) 규칙이 분리되며, 비밀 정보(secrets)는 가려집니다.
• 파일 크기 초과, 파일 내 중복 규칙, 깨진 @import 참조, 그리고 검토가 필요한 비밀 정보와 유사한 값에 대한 경고 (warnings).

Workplace Scan - ContextGuard

Status bar - ContextGuard

Preview injected context - ContextGuard

각 어시스턴트별로 단일 요청 시 각 도구가 실제로 무엇을 로드하는지 보여주는 뷰(view)는 로드맵에 포함되어 있습니다.

이것은 무료이며, 로컬 우선(local-first) 방식이고, 결정론적(deterministic)입니다. 모든 발견 사항은 파일 및 줄(line)과 연결되어 있으며, AI 호출이 발생하지 않고, 어떤 데이터도 사용자의 기기를 떠나지 않습니다. 텔레메트리(telemetry)도 없습니다.

때때로 모델이 완벽하게 명확한 지시를 정말로 무시할 때가 있습니다. 하지만 때로는 우리가 수천 토큰의 누적된 정책을 전달하고, 중요한 규칙을 세 군데에 복사해 넣은 뒤, 모델이 어떤 문장이 가장 중요한지 알기를 기대하기도 합니다.

지시문 파일(instruction files)이 에이전트(agent)의 동작을 변경할 수 있다면, 그것들은 소프트웨어의 일부입니다. 저는 우리가 그것들을 그렇게 취급하기 시작해야 한다고 생각합니다. 즉, 지시문을 검토하고, 크기를 주시하며, 동일한 규칙의 약간씩 다른 세 가지 복사본을 유지하는 것을 피해야 합니다.

에이전트를 탓하기 전에, 당신이 타이핑하지 않은 프롬프트(prompt)를 점검하십시오.

→ VS Code Marketplace의 ContextGuard · 내가 스캔한 리포지토리 목록

당신의 메인 리포지토리(repo)에는 얼마나 많은 AI 지침 파일(instruction files)이 놓여 있으며, 마지막으로 이 파일들을 함께 검토한 적은 언제입니까?