컨텍스트 파일 작성하기 (AGENTS.md)

당신이 할 수 있는 가장 지렛대 효과가 큰 일은 AI가 자동으로 읽는 컨텍스트 파일을 작성하는 것이다. 도구마다 찾는 이름이 다르다 — AGENTS.md, CLAUDE.md, .cursorrules, 또는 .github/copilot-instructions.md — 하지만 발상은 동일하다: 당신의 프로젝트가 어떻게 동작하고 당신이 AI가 어떻게 행동하길 원하는지 알려주는 살아있는 문서.

이것이 없으면 AI는 추측한다. 이것이 있으면 AI는 당신의 코드 재포맷팅을 멈추고, 쓰지도 않는 라이브러리를 지어내기를 멈추고, 이미 내린 결정을 다시 설명하기를 멈춘다. 이를 뛰어나지만 세션 사이에 완전한 기억상실에 걸리는 새 팀원을 위한 온보딩 문서라고 생각하라 — 그들이 생산적이 되는 데 필요한 모든 것은 그들이 매번 읽을 어딘가에 있어야 한다.

실용적인 시작 파일:

# Project: Invoice Manager

## What this is
A small web app for freelancers to create and track invoices.

## Tech stack
- TypeScript + React (Vite)
- Tailwind for styling
- SQLite via Prisma
- Vitest for tests

## Commands
- Install: `npm install`
- Run dev server: `npm run dev`
- Run tests: `npm test`
- Lint: `npm run lint`

## Conventions
- Use functional components and hooks; no class components.
- Keep components small; one component per file.
- Write a test for every new function in `src/lib`.
- Never edit files in `src/generated/` — they are auto-generated.

## Don'ts
- Don't add new dependencies without flagging it first.
- Don't commit secrets; use environment variables.

짧게 유지하고 최신으로 유지하라. 천 줄까지 불어난 컨텍스트 파일은 — 당신에게도 모델에게도 — 더 이상 꼼꼼히 읽히지 않으니, 추가하는 만큼이나 공격적으로 쳐내라. AI가 같은 잘못된 가정을 반복할 때, 그것이 한 줄을 추가하라는 신호다; 규칙이 더 이상 현실과 맞지 않으면, 그것이 에이전트를 적극적으로 오도하기 시작하기 전에 지워라.

작동하는 컨텍스트 파일과 무시되는 컨텍스트 파일을 가르는 몇 가지 패턴이 있다:

• 구체적이고 명확하게 써라. "우리 컨벤션을 써라"는 쓸모없다. "검증에는 zod를 써라; 우리는 yup을 쓰지 않는다"는 AI가 실제로 따를 수 있는 규칙이다.
• 하지 말 것을 할 것만큼 크게 말하라. 모델은 돕고 싶어 안달이고, 그래서 당신이 말리지 않으면 기꺼이 의존성을 추가하거나 설정을 다시 쓴다.
• 예시를 가리켜라. "src/features/invoices의 스타일에 맞춰라"는 해석할 모호한 지시 대신 베껴올 구체적인 모델을 AI에게 준다.

컨텍스트 파일을, 그렇지 않았다면 매번 반복해야 했을 모든 교훈의 기록으로 다뤄라. 그것은 이 장 전체에서 가장 값싸고 가장 오래가는 투자다.