AI 도구에 대해 팀원과 처음으로 실제로 다퉜던 문제는 어떤 모델을 사용할 것인가에 대한 것이 아니었습니다. 그것은 우리가 어떤 설정 파일 (config file)을 편집해야 하는지에 관한 것이었습니다. 저장소 루트에는 제가 지난 2월에 작성한 CLAUDE.md가 있었습니다. 3월에 합류한, Cursor만 사용하고 Claude Code는 열어보려고도 하지 않는 엔지니어가 만든 .cursorrules 파일이 있었습니다. .github/ 폴더 아래에는 조직을 위해 Copilot을 활성화한 누군가가 넣어둔 copilot-instructions.md가 있었습니다. 그리고 누군가 컨퍼런스에서 듣고 가져온 절반쯤 비어 있는 AGENTS.md가 있었습니다. 네 개의 파일. 네 가지의 서로 다른 진실. 데이터베이스 마이그레이션 (database migration)을 작성하는 방법에 대한 미묘하게 다른 세 가지 의견. 공유된 이해는 제로였습니다.

논쟁을 촉발한 버그는 사소했습니다. 한 주니어 엔지니어가 Cursor에게 Postgres 마이그레이션을 작성해 달라고 요청했습니다. Cursor는 자체 규칙에 따라 괜찮은 결과물을 만들어냈습니다. PR 리뷰에서는 "우리의 컨벤션 (convention)은 항상 마이그레이션을 트랜잭션 (transaction)으로 감싸고 롤백 (rollback)을 작성하는 것입니다"라고 지적했습니다. 주니어 엔지니어는 .cursorrules를 가리켰습니다. 트랜잭션에 대한 내용은 없었습니다. 우리는 CLAUDE.md를 확인했습니다. 거기에는 규칙이 있었습니다. copilot-instructions.md를 확인했습니다. 표현은 달랐지만 의도는 같았습니다. AGENTS.md를 확인했습니다. 비어 있었습니다. 규칙이 추가되었을 때 아무도 Cursor를 사용하지 않았기 때문에, 아무도 Cursor의 파일에 그 규칙을 작성하지 않았던 것입니다. 모델은 파일이 지시한 대로 정확히 수행했습니다. 파일이 방치되어 잘못되었을 뿐이었습니다.

이것이 2026년 팀 코딩 표준의 새로운 모습입니다. 표준은 존재합니다. 다만 다섯 군데의 장소에서, 다섯 가지의 형식으로, 다섯 가지의 서로 다른 업데이트 일정으로 존재할 뿐입니다. 만약 당신이 하나 이상의 AI 코딩 도구를 사용하는, 두 명보다 많은 인원의 팀을 이끌고 있다면 이 글은 당신을 위한 것입니다. 저는 각 설정 파일이 실제로 무엇을 하는지, 의미 있는 차이점은 무엇인지, 그리고 마침내 우리 팀을 월요일의 논쟁 루프에서 벗어나게 해준 레이아웃이 무엇인지 설명하겠습니다.

현재 당신의 코드베이스를 실행하는 네 개의 파일
무엇인가를 비교하기 전에, 라인업을 소개합니다. 실제로 존재하는 설정 파일은 네 개보다 많지만, 당신이 실제로 신경 써야 할 것은 바로 이것들입니다.

CLAUDE.md는 Claude Code 설정 파일입니다. 이 파일은 저장소(repo)의 루트에 위치하거나(또는 개인용 전역 규칙을 위해 ~/.claude/CLAUDE.md에 위치함), Claude Code는 세션이 시작될 때마다 이를 읽고 그 내용을 영구적인 시스템 프롬프트 (system prompt)로 취급합니다. 이 파일은 최대 5단계 깊이까지의 @path/to/file 임포트 (import)를 지원하므로, 표준을 여러 파일로 분할하여 참조할 수 있습니다. 또한 Claude가 세션 중 사용자의 수정 사항과 선호도를 바탕으로 메모리 디렉토리에 노트를 다시 작성하는 자동 메모리 (auto-memory) 기능도 지원합니다. .cursorrules (또는 더 최신 방식인 .cursor/rules/.mdc 디렉토리 레이아웃)는 Cursor 설정 파일입니다. 기존의 .cursorrules는 단일 마크다운 (Markdown) 파일입니다. 새로운 디렉토리 형식은 프론트매터 (frontmatter)를 통해 규칙이 적용되는 시점을 제어하는 여러 규칙을 가질 수 있게 해줍니다. 프론트매터는 글로브 (globs), alwaysApply, 그리고 description 필드를 지원하므로, .tsx 파일에 대해서만 실행되는 규칙이나 사용자가 마이그레이션 (migrations)에 대해 물을 때만 실행되는 규칙을 만들 수 있습니다. 이는 진정으로 유용하며, 제가 본 대부분의 팀에서 아직 충분히 활용되지 않고 있는 기능입니다. copilot-instructions.md는 GitHub Copilot 설정 파일입니다. 이 파일은 .github/copilot-instructions.md에 위치하며 Copilot Chat, 코드 리뷰 (code review), 그리고 자율 코딩 에이전트 (autonomous coding agent)에 적용됩니다. Copilot은 또한 글로브 패턴 (glob patterns)을 사용하는 YAML 프론트매터가 포함된 .github/instructions/.instructions.md 경로별 지침 (path-specific instructions)도 지원합니다. 경로별 파일은 루트 파일과 모두 일치할 경우 두 파일이 결합되므로, TypeScript 규칙과 일반 규칙이 모두 .ts 파일에 적용됩니다. AGENTS.md는 이 생태계에서 중립적인 표준에 가장 가까운 파일입니다. 이는 OpenAI Codex CLI 설정으로 시작되었으며, 이후 Cursor, Aider, 그리고 몇몇 소규모 도구들이 폴백 (fallback) 용도로 채택했습니다. 이 파일은 화려한 기능은 지원하지 않습니다. 임포트 (imports), 글로브 (globs), 경로별 오버라이드 (path-specific overrides) 등이 없습니다. 그저 규격에 맞는 에이전트라면 무엇이든 읽을 수 있는 평범한 마크다운 (Markdown)일 뿐입니다. 가장 폭넓은 도구 간 지원을 의미한다는 것은, 동시에 가장 낮은 공통 분모 (lowest common denominator)라는 뜻이기도 합니다. 그 외에도 다른 것들이 있습니다. Google Gemini CLI를 위한 GEMINI.md, Windsurf를 위한 .windsurfrules, 그리고 Warp의 에이전트 모드를 위한 WARP.md가 있습니다.

패턴은 위의 네 가지와 동일합니다. 팀이 실제로 사용하는 것들만 선택하고 나머지는 무시하세요.

각 파일이 실제로 잘하는 것
이 파일들을 서로 교체 가능한 것으로 취급하는 것이 대부분의 팀이 저지르는 첫 번째 실수입니다. 그렇지 않습니다. 이들이 지원하는 기능이 다르며, 각 파일에 최적화된 콘텐츠도 다릅니다. 제가 각 파일을 실제로 사용해 온 방식은 다음과 같습니다.

CLAUDE.md는 시스템 내에서 가장 오래 지속되며, 가장 주관적인(opinionated) 파일입니다. Claude Code의 하네스(harness)는 세 가지 주요 도구 중 가장 자율적이며, 이는 당신이 작성한 규칙이 가장 큰 영향력(leverage)을 발휘한다는 것을 의미합니다. "작업 완료를 선언하기 전에 항상 타입 체크(typecheck)를 실행하라"와 같은 단 한 문장이 실제로 40단계에 걸친 에이전트 세션 전체의 동작을 변화시킵니다. @import 기능을 사용하면 표준을 주제별 파일(@.claude/standards/api.md, @.claude/standards/testing.md, @.claude/standards/database.md)로 분리하고 루트 파일을 목차(table of contents)로 유지할 수 있습니다. 이것이 현재 제가 구조를 잡는 방식입니다. 또한 자동 메모리(auto-memory) 레이어 덕분에 당신이 일일이 관리하지 않아도 CLAUDE.md는 시간이 지남에 따라 계속 성장합니다. 이는 모델이 무엇을 기억할지에 대한 판단을 얼마나 신뢰하느냐에 따라 기능이 될 수도 있고, 실수 유발 요소(footgun)가 될 수도 있습니다. 저는 '에이전트 코딩 2026(agentic coding 2026)' 글에서 더 광범위한 Claude Code 워크플로우를 다루었습니다. 요약하자면, 장기 실행되는 에이전트에 대한 영향력이 매우 높기 때문에 CLAUDE.md가 가장 많은 편집적 관리(editorial care)를 할 가치가 있다는 것입니다.

Cursor rules는 경로별 오버라이드(path-specific overrides)로 취급하는 것이 가장 좋습니다. 글로브(globs) 패턴을 사용하는 새로운 .cursor/rules/*.mdc 형식은 핵심 기능(killer feature)입니다. 저는 *.test.ts 파일에 대해서만 실행되며 에이전트에게 데이터베이스 레이어에 대해 절대 모의 객체(mocks)를 사용하지 말라고 지시하는 규칙을 가지고 있습니다. 또 다른 규칙은 *.tsx 파일에 대해서만 실행되며 에이전트에게 우리가 사용하는 디자인 토큰(design tokens)을 알려줍니다. .cursor/rules/ 아래의 기본 파일은 작고 일반적인 상태로 유지됩니다. 경로별 파일들이 실질적인 작업(heavy lifting)을 수행합니다. 만약 루트에 600줄짜리 .cursorrules를 작성한다면, 당신은 도구를 잘못 사용하고 있는 것입니다. 분리하세요.

Copilot instructions는 저장소 전체에 적용되는 진리(repo-wide truths)를 정의하는 데 가장 적합합니다.

Copilot의 강점은 범위(breadth)입니다. 확장을 사용하는 모든 개발자는 좋든 싫든 이를 읽게 됩니다. 약점은 지침(instructions)이 짧고, CLAUDE.md보다 더 공격적으로 잘려 나가며(truncated), 긴 자율 세션(autonomous sessions)보다는 주로 Copilot Chat과 PR 리뷰 에이전트(PR-review agent)를 위해 사용된다는 점입니다. copilot-instructions.md에 들어갈 적절한 내용은 모든 개발자의 자동 완성(autocomplete)과 PR 리뷰 에이전트가 반드시 준수하기를 원하는 고신호 규칙(high-signal rules)입니다. 스택 선택 사항, 금지된 패턴(Banned patterns), PR에 절대 포함되어서는 안 될 다섯 가지 사항 같은 것들 말이죠. 아키텍처에 관한 200줄짜리 에세이가 아닙니다.

AGENTS.md는 예의를 갖추기 위한 파일입니다. 이 파일의 역할은 다른 파일들을 읽지 않는 도구들을 위해 존재하는 것입니다. 이를 진리(source of truth)가 아닌 리다이렉트(redirect)로 취급하세요. 제 프로젝트에서 사용하는 전형적인 AGENTS.md는 20줄 정도입니다: "전체 표준은 CLAUDE.md를 참조하세요. 가장 중요한 사항은 A, B, C입니다. 작업이 완료되었다고 하기 전에 bun test를 실행하세요." 이 정도면 익숙하지 않은 에이전트가 전체 CLAUDE.md 컨텍스트를 필요로 하지 않고도 합리적인 작업을 수행하기에 충분합니다.

팀들이 저지르는 실수는 이 네 가지를 모두 병렬적인 것으로 취급하는 것입니다. 그렇지 않습니다. 여기에는 계층 구조(hierarchy)가 있습니다.

최종적으로 작동한 레이아웃(The Layout That Finally Worked)
이 문제로 세 달 동안 씨름한 끝에, 저희 팀이 결정한 레이아웃은 다음과 같습니다. 이 레이아웃은 지난 6개월 동안 안정적으로 유지되었는데, 이는 저희 조직에서 AI 툴링(tooling) 결정이 지속된 기간 중 가장 긴 시간입니다.

저희는 하나의 진리(source of truth)를 가집니다: .claude/standards/
그 내부에는 주제별로 파일이 하나씩 있습니다.
.claude/standards/ api.md database.md testing.md frontend.md observability.md security.md

각 파일은 100~200줄 정도로 짧습니다. 각 파일은 해당 분야의 팀 리드(team lead)가 검토합니다. 모든 파일은 동일한 구조를 가집니다: 의도를 담은 한 단락의 문장, 그 다음 이유를 포함한 규칙 목록, 마지막으로 이유를 포함한 금지 사항 목록입니다. 이 구조는 중요합니다. 작성자가 규칙을 정당화하도록 강제하기 때문입니다. 이유가 없는 규칙은 삭제됩니다. 루트(root) CLAUDE.md는 주제별 파일들을 임포트(import)하고, 특정 도메인에 속하지 않는 횡단적 규칙(cross-cutting rules)을 추가하는 30줄짜리 파일입니다.

프로젝트 표준 (Project Standards)

이 프로젝트는 Bun, Postgres, Astro, Vercel을 사용합니다.

주제별 표준 (Topical standards)

@.claude/standards/api.md
@.claude/standards/database.md
@.claude/standards/testing.md
@.claude/standards/frontend.md
@.claude/standards/observability.md
@.claude/standards/security.md

횡단적 규칙 (Cross-cutting rules)

• 행(rows)을 먼저 보여주지 않고는 파괴적인 SQL을 절대 실행하지 마십시오.
• 작업 완료를 선언하기 전에 항상 bun test와 bun run typecheck를 실행하십시오.
• 우리가 배포하는 어떤 파일에도 엠 대시(em dashes)를 사용하지 마십시오. 절대 안 됩니다.

워크플로우 (Workflow)

• 우리는 트렁크 기반 개발 (trunk-based development)을 사용합니다. 기능 브랜치 (Feature branches)는 수명이 짧습니다.
• PR (Pull Requests)은 해당 영역 소유자 (area owner)에 의해 검토됩니다. 큰 변경 사항은 먼저 Linear 티켓을 생성해야 합니다.

이것이 루트 파일의 전부입니다. 그 외의 모든 것은 임포트 (import)를 통해 불러와집니다. AGENTS.md는 15줄이며 동일한 표준을 가리킵니다. 이는 임포트할 수 없는 도구들을 위한 폴백 (fallback) 기능을 갖춘 리다이렉트 (redirect) 파일입니다.

에이전트 표준 (Agent Standards)

전체 규칙은 .claude/standards/를 참조하십시오. 만약 해당 파일들을 읽을 수 없다면, 반드시 따라야 할 네 가지 규칙은 다음과 같습니다:

1. npm이나 yarn이 아닌 Bun을 사용하십시오.
2. 행(rows)을 먼저 보여주지 않고는 데이터베이스에 절대 쓰지 마십시오.
3. 변경 후에는 항상 bun test와 bun run typecheck를 실행하십시오.
4. 기존의 코드 스타일과 임포트 순서를 따르십시오.

전체 표준: github.com/our-org/our-repo/tree/main/.claude/standards

copilot-instructions.md는 동일한 내용을 담고 있지만, Copilot의 더 짧은 컨텍스트 윈도우 (context window)에 맞춰 압축되어 있습니다. 우리는 프리 커밋 (pre-commit) 시 실행되는 작은 스크립트를 사용하여 주제별 파일들로부터 이를 자동 생성합니다. 이를 통해 Copilot이 전체 표준이 아닌 요약본을 읽는다는 점을 감수하는 대신, 내용이 어긋나는 드리프트 (drift) 문제를 제거합니다.

Cursor 규칙은 .cursor/rules/에 위치하며 글로브 (globs) 패턴에 연결됩니다.
database.mdc 규칙의 글로브는 ["**/migrations/**", "**/db/**"]입니다.
testing.mdc 규칙의 글로브는 ["**/*.test.ts", "**/*.spec.ts"]입니다.
frontend.mdc 규칙의 글로브는 ["**/*.tsx", "**/*.css"]입니다.
각 규칙은 대응하는 .claude/standards/ 파일의 관련 내용을 담고 있습니다. 이들 역시 동일한 소스로부터 자동 생성됩니다.

생성을 수행하는 스크립트는 50줄 정도의 TypeScript로 작성되었습니다. 이 스크립트는 주제별 파일들을 읽고, 짧은 형식(shorter formats)을 위해 이유 설명 단락(reason-paragraphs)을 제거하고 규칙 라인(rule lines)만 남기는 압축기(compressor)를 적용한 뒤, 네 개의 출력 파일을 작성합니다. Pre-commit 단계에서 이 스크립트가 실행됩니다. PR(Pull Request) 리뷰 과정에서는 생성된 파일들이 동기화되어 있는지 확인합니다. 만약 생성된 파일을 수동으로 편집하면, 훅(hook)이 오류를 발생시킵니다. 핵심은 반드시 이와 똑같은 레이아웃을 가질 필요가 있다는 것이 아닙니다. 핵심은 단일 진실 공급원(one source of truth)을 확보하고, 이를 모든 도구가 읽고자 하는 형식으로 투영(project)할 방법을 갖추는 것입니다. 이것이 없다면, 여러분은 네 개의 병렬적인 규칙 코드베이스를 운영하게 되며, 그중 하나는 소리 없이 어긋나게(drift) 될 것입니다.

실제로 드리프트(Drift)를 유발하는 요인들
파일 레이아웃을 이해했다면, 다음 문제는 시간이 흐름에 따라 콘텐츠를 동기화된 상태로 유지하는 것입니다. 여기서 대부분의 팀이 실패하며, 실패 양상은 항상 동일합니다.

하나의 파일에만 새로운 규칙이 추가되고 다른 파일에는 추가되지 않는 경우입니다. 예를 들어, 시니어 엔지니어가 사고 발생 후 CLAUDE.md에 트랜잭션 래퍼(transaction wrappers)에 관한 규칙을 추가했다고 가정해 봅시다. 6개월 후, Cursor를 사용하는 주니어 엔지니어가 해당 규칙이 방지하고자 했던 바로 그 코드를 생성하게 됩니다. Cursor가 그 규칙을 전혀 보지 못했기 때문입니다. 해결책은 앞서 언급한 투영 계층(projection layer)입니다. 하나의 소스, 여러 개의 출력물. 규칙을 추가한다는 것은 한 곳에 추가하고 스크립트가 나머지를 처리하도록 맡기는 것을 의미합니다.

오래된 규칙은 절대 삭제되지 않습니다. AI 코딩 표준 파일은 계속해서 커지는 경향이 있습니다. 2024년에 작성된 지원 중단된(deprecated) 라이브러리에 관한 규칙이 2026년에도 파일에 남아 있을 수 있습니다. 모델은 이를 성실히 따릅니다. 새로 합류한 엔지니어는 왜 자신의 코드가 계속 Lodash를 사용하도록 재작성되는지 의아해합니다. 해결책은 분기별 검토(quarterly review)입니다. 분기당 한 번, 30분 동안 팀 리더가 각 주제별 파일을 훑어보며, 아무도 방어할 수 없는 규칙은 삭제합니다. 우리는 추가하는 것보다 더 많이 삭제합니다. 파일 크기는 연간 약 20%씩 줄어듭니다. 이것이 건강한 상태입니다.

이유가 소실됩니다. 이유 없이 존재하는 규칙은 리팩터링(refactor)이 불가능합니다. 원래의 맥락(context)이 사라졌기 때문에, 팀은 해당 규칙이 여전히 유효한지 평가할 수 없습니다.

해결책은 모든 규칙에 이유를 요구하는 것입니다. 저희는 Claude Code의 피드백 메모리(feedback memories)와 동일한 구조를 사용합니다. 즉, 규칙 자체를 작성한 뒤, '이유(Why):'와 '적용 방법(How to apply):' 라인을 추가하는 방식입니다. 이유는 필수 사항입니다. 만약 그 이유를 명확하게 설명할 수 없다면, 해당 규칙은 파일에 포함되어서는 안 됩니다. 표준이 코드베이스(codebase)와 모순되는 경우가 있습니다. 예를 들어, 한 규칙이 "클라이언트 측 데이터 페칭(data fetching)에는 항상 Tanstack Query를 사용하라"고 명시되어 있다고 가정해 봅시다. 하지만 코드베이스에는 해당 규칙이 만들어지기 전의 코드인 SWR 호출이 40개나 남아 있습니다. 모델은 이 두 가지를 모두 보고 무작위로 하나를 선택합니다. 해결책은 코드베이스를 마이그레이션(migrate)하거나 규칙을 업데이트하는 것뿐입니다. 제3의 선택지는 없습니다. 현실과 모순되는 표준은 표준이 아예 없는 것보다 더 나쁩니다. 왜냐하면 모델에게 전반적으로 표준을 무시하도록 가르치기 때문입니다. 개인적인 선호도가 팀에 몰래 스며들기 시작합니다