AI 코딩 툴체인 5계층: 규칙·접근 차단·에이전트 확장·리뷰·자동 검증 설정 파일 정리

AI 코딩 도구 목록은 몇 달마다 바뀌지만, 도구를 팀에 안전하게 붙이는 데 필요한 장치는 크게 바뀌지 않는다. 에이전트가 따를 규칙, 읽으면 안 되는 파일의 차단, 외부 도구 연결, 사람 리뷰, 기계적 검증이다. 이 글은 스택을 제품 순위가 아니라 저장소에 있어야 할 설정 파일 다섯 계층으로 정리하고, 그 파일들이 실제로 있는지 확인하는 점검 스크립트를 제공한다.

다섯 계층과 대표 설정 파일

계층별 최소 예시

1. 규칙: 도구 공통 AGENTS.md

Cursor는 AGENTS.md를 .cursor/rules의 단순한 대안으로 지원하고, Copilot도 저장소의 AGENTS.md를 에이전트 지침으로 읽는다. 여러 도구를 쓰는 팀은 공통 규칙을 여기에 둔다. 작성 요령은 Cursor Rules 작성법에서 다룬다.

# AGENTS.md
## 명령
- 설치: npm ci
- 테스트: npm test -- --run
- 타입 검사: npx tsc --noEmit

## 규칙
- src/api/** 핸들러는 요청 본문을 Zod로 검증한다.
- 새 의존성 추가 전에 PR 설명에 이유를 적는다.
- .env, secrets/ 아래 파일은 읽거나 출력하지 않는다.

2. 접근 차단: Claude Code 권한 설정

규칙 파일의 "읽지 않는다"는 요청일 뿐이다. 실제 차단은 도구 설정으로 한다. Claude Code는 프로젝트의 .claude/settings.json에서 도구별 거부 규칙을 둔다. 도구별 차단 범위의 차이는 시크릿·.env 차단 설정에서 비교했다.

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
  }
}

3. 에이전트 확장: 팀이 공유하는 MCP 설정

MCP 서버 설정을 저장소의 .mcp.json에 두면 팀원이 같은 서버 목록을 쓴다. 아래는 이 사이트 저장소에 실제로 있는 설정이다. 서버를 늘리기 전 점검 항목은 파일시스템·브라우저 MCP 안전 설정을 참고한다.

{
  "mcpServers": {
    "chrome-devtools": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "chrome-devtools-mcp@latest"],
      "env": {}
    }
  }
}

4·5. 리뷰와 자동 검증

리뷰 계층은 PR 템플릿과 CODEOWNERS가 최소 단위다. 구체적인 템플릿과 PR 본문 검사 스크립트는 AI 생성 코드 리뷰 규칙에, 커밋 전 검증 설정은 커밋 전 ESLint·Prettier·tsc 자동화에 정리했다.

저장소 점검 스크립트

아래 스크립트는 저장소를 읽기만 하고, 계층별로 대표 파일이 있는지 출력한다. 파일이 있다고 설정이 올바르다는 뜻은 아니므로, 결과는 "무엇이 비어 있는가"를 찾는 출발점으로 쓴다.

// 사용법: node ai-stack-audit.mjs [저장소 경로]
// 저장소에 AI 코딩 도구 설정 파일이 계층별로 있는지 확인한다(읽기 전용).
import { existsSync, readdirSync, statSync } from 'node:fs';
import { join } from 'node:path';

const root = process.argv[2] || '.';
const has = (p) => existsSync(join(root, p));
const countIn = (dir, ext) =>
  has(dir) && statSync(join(root, dir)).isDirectory()
    ? readdirSync(join(root, dir)).filter((f) => f.endsWith(ext)).length
    : 0;

const layers = [
  ['1. 컨텍스트(규칙)', [
    ['AGENTS.md', has('AGENTS.md')],
    ['CLAUDE.md', has('CLAUDE.md')],
    ['.github/copilot-instructions.md', has('.github/copilot-instructions.md')],
    [`.cursor/rules/*.mdc (${countIn('.cursor/rules', '.mdc')}개)`, countIn('.cursor/rules', '.mdc') > 0],
  ]],
  ['2. 접근 차단', [
    ['.cursorignore', has('.cursorignore')],
    ['.claude/settings.json (permissions)', has('.claude/settings.json')],
  ]],
  ['3. 에이전트 확장', [
    [`.claude/skills (${has('.claude/skills') ? readdirSync(join(root, '.claude/skills'), { withFileTypes: true }).filter((d) => d.isDirectory()).length : 0}개)`, has('.claude/skills')],
    ['.mcp.json', has('.mcp.json')],
    ['.cursor/mcp.json', has('.cursor/mcp.json')],
  ]],
  ['4. 리뷰', [
    ['.github/pull_request_template.md', has('.github/pull_request_template.md')],
    ['CODEOWNERS', has('.github/CODEOWNERS') || has('CODEOWNERS') || has('docs/CODEOWNERS')],
    ['.cursor/BUGBOT.md', has('.cursor/BUGBOT.md')],
  ]],
  ['5. 자동 검증', [
    [`.github/workflows (${countIn('.github/workflows', '.yml')}개)`, countIn('.github/workflows', '.yml') > 0],
    ['.husky / lint-staged', has('.husky') || has('.lintstagedrc') || has('.lintstagedrc.json')],
  ]],
];

for (const [name, items] of layers) {
  const ok = items.filter(([, v]) => v).length;
  console.log(`${name}  ${ok}/${items.length}`);
  items.forEach(([label, v]) => console.log(`   ${v ? '있음' : '없음'}  ${label}`));
}

이 사이트 저장소에 실행한 결과

2026-10-07에 이 사이트를 빌드하는 저장소에 스크립트를 실행했다. 정적 사이트 생성과 콘텐츠 작업을 Claude Code 스킬로 처리하는 1인 운영 저장소다.

$ node ai-stack-audit.mjs .
1. 컨텍스트(규칙)  0/4
   없음  AGENTS.md
   없음  CLAUDE.md
   없음  .github/copilot-instructions.md
   없음  .cursor/rules/*.mdc (0개)
2. 접근 차단  1/2
   없음  .cursorignore
   있음  .claude/settings.json (permissions)
3. 에이전트 확장  2/3
   있음  .claude/skills (9개)
   있음  .mcp.json
   없음  .cursor/mcp.json
4. 리뷰  0/3
   없음  .github/pull_request_template.md
   없음  CODEOWNERS
   없음  .cursor/BUGBOT.md
5. 자동 검증  0/2
   없음  .github/workflows (0개)
   없음  .husky / lint-staged

결과를 보면 에이전트 확장 계층(스킬 9개, MCP 설정)은 갖췄지만 규칙 파일이 없다. 이 저장소는 규칙을 각 스킬의 SKILL.md와 참고 문서 안에 넣어 두었기 때문인데, 스킬 밖에서 작업을 요청하면 그 규칙이 적용되지 않는다는 뜻이기도 하다. 리뷰·자동 검증 계층이 비어 있는 것은 1인 운영이라 PR 없이 기본 브랜치에 바로 푸시하는 구조이기 때문이다. 대신 배포 스킬이 푸시 전에 빌드와 사이트 검증 스크립트를 실행한다. 팀 저장소라면 이 두 계층이 가장 먼저 채워야 할 부분이다.

빈 계층을 채우는 순서

1. 접근 차단부터 설정한다. 다른 계층은 나중에 추가해도 되지만, 비밀값이 한 번 컨텍스트로 들어가면 되돌릴 수 없다.
2. 규칙 파일에 빌드·테스트 명령과 금지 패턴만 적는다. 처음부터 길게 쓰지 말고 리뷰에서 반복된 지적을 추가해 간다.
3. 자동 검증(타입·린트·테스트)을 CI에 연결한다. AI 리뷰 봇보다 먼저 둔다.
4. 리뷰 계층에 PR 템플릿과 CODEOWNERS를 둔다.
5. 에이전트 확장은 반복 절차가 분명해진 뒤 스킬이나 MCP 서버로 만든다.