당신은 Scrapy 스크레이퍼(scraper)를 만들고 있습니다. Claude Code에게 도움을 요청합니다. "내 스파이더(spider)에 페이지네이션(pagination)을 추가해줘."

Claude는 당신의 코드를 읽습니다. scraper.py, settings.py, 폴더 구조를 확인합니다. 그러고 나서 제안을 합니다.

하지만 그 제안들은 당신의 스타일과 맞지 않습니다. 당신은 특정한 명명 규칙(naming conventions)을 사용합니다. 당신의 에러 핸들링(error handling)은 독특합니다. 당신의 Scrapy 미들웨어(middleware)는 커스텀(custom) 방식입니다. Claude는 이 중 아무것도 알지 못합니다.

그래서 Claude는 기술적으로는 작동하지만, 당신에게 맞지 않는 코드를 작성합니다. 당신은 당신의 패턴에 맞추기 위해 코드를 다시 쓰는 데 30분을 소비합니다. 다시 요청합니다. 똑같은 문제입니다. Claude는 학습하지 않습니다. 매번 모든 것을 설명해야 합니다.

이것은 좌절감을 줍니다. 당신은 AI가 당신의 프로젝트를 이해하기를 원합니다. 단순히 코드뿐만 아니라, 철학(philosophy), 패턴(patterns), 컨벤션(conventions), 그리고 당신이 실제로 일하는 방식을 말입니다.

그러다 당신은 agents.md를 발견합니다.

단순한 Markdown 파일입니다. 프로젝트 루트(root)에 넣기만 하면 됩니다. 이것은 AI 에이전트(AI agents)에게 당신이 어떻게 일하는지 가르칩니다. 당신의 명명 규칙, 아키텍처 결정(architectural decisions), 스크래핑 패턴, 에러 핸들링 접근 방식 등 모든 것을 말입니다.

이제 Claude Code에게 도움을 요청하면, Claude는 먼저 agents.md를 읽습니다. Claude는 당신의 프로젝트를 이해합니다. Claude가 작성하는 코드는 즉시 당신의 스타일과 일치합니다. 다시 쓸 필요도, 같은 말을 반복할 필요도 없습니다.

당신은 더 이상 단순한 스크레이퍼를 만드는 것이 아닙니다. 당신은 AI에게 스크레이퍼를 만드는 법을 가르치는 스크레이퍼를 만들고 있는 것입니다.

이것이 agents.md입니다. 그리고 이것은 개발자가 AI와 협업하는 방식을 바꾸고 있습니다.

직접 보여드리겠습니다.

agents.md의 실체 (그리고 이것이 중요한 이유)

agents.md는 AI 코딩 에이전트(AI coding agents)에게 당신의 프로젝트에서 어떻게 작업해야 하는지 가르치는 Markdown 파일입니다.

이렇게 생각해보세요:

README.md는 사람들에게 당신의 프로젝트에 대해 가르칩니다. 프로젝트가 무엇을 하는지, 어떻게 설치하는지, 어떻게 기여(contribute)하는지를 말이죠.

agents.md는 AI에게 당신의 프로젝트에 대해 가르칩니다. 당신이 사용하는 패턴, 당신이 내린 결정, 당신의 스타일에 맞는 코드를 작성하는 법을 말입니다.

둘 다 프로젝트에 존재합니다. 둘 다 중요합니다. 다만 서로 다른 대상(audience)을 위해 존재할 뿐입니다.

이것이 스크레이퍼에게 중요한 이유

Scrapy 프로젝트는 복잡합니다. 스파이더 (spiders), 파이프라인 (pipelines), 미들웨어 (middleware), 설정 (settings) 등이 존재합니다. 에러 처리 (error handling)를 위한 패턴도 있고, 명명 규칙 (naming conventions)도 있습니다. 데이터가 어떻게 흐르는지에 대한 아키텍처적 결정 (architectural decisions)도 포함됩니다.

AI에게 도움을 요청할 때, AI는 이 모든 복잡성을 봅니다. 하지만 패턴을 이해하지는 못합니다. 철학을 이해하지 못합니다. 당신이 스크래핑 (scraping)에 대해 생각하는 방식을 이해하지 못합니다.

agents.md가 이 문제를 해결합니다.

당신은 패턴을 한 번만 문서화하면 됩니다. 그러면 AI가 이를 읽습니다. 이제 모든 제안과 생성된 모든 코드 조각은 자동으로 당신의 패턴을 따르게 됩니다.

차이점은 무엇인가: agents.md vs SKILL.md vs CLAUDE.md?

이 개념에는 몇 가지 변형이 있습니다:

agents.md: 모든 AI 코딩 에이전트 (AI coding agent)를 위한 개방형 표준 (Open standard)입니다. GitHub Copilot, Cursor, OpenAI Codex CLI 등과 함께 작동합니다.

SKILL.md: 특정 재사용 가능한 기술 (reusable skills)을 위한 Anthropic의 형식입니다. 더 구조화되어 있으며, 기술당 별도의 폴더를 가집니다.

CLAUDE.md: Claude Code의 특정 변형입니다 (더 최신이며 더 많은 기능을 제공함).

agents.md는 범용 형식 (universal format)입니다. 어디에서나 작동합니다. 이 블로그는 agents.md에 집중합니다.

기본 구조

agents.md는 두 부분으로 구성됩니다:

1. YAML 프론트매터 (YAML frontmatter, 프로젝트에 대한 메타데이터)
2. 마크다운 본문 (Markdown body, 에이전트를 위한 지침)

간단한 예시

다음은 최소한의 agents.md 파일입니다:

---
name: ecommerce-scraper
description: Web scraper for e-commerce product data
...

그게 전부입니다. 간단합니다. 에이전트는 이를 읽고, 당신의 프로젝트를 이해하며, 당신의 스타일을 따릅니다.

YAML 프론트매터의 구성 요소

name: 프로젝트 식별자 (내부적으로 사용됨)

description: 짧은 설명 (50-100자). 에이전트에게 이 파일을 언제 사용해야 하는지 알려줍니다.

선택적 필드 (Optional fields):

---
name: ecommerce-scraper
description: Web scraper for e-commerce product data
...

이 필드들은 에이전트가 프로젝트 범위 (project scope)를 이해하는 데 도움을 줍니다. 선택 사항이지만 팀 단위 작업 시 유용합니다.

Scrapy 프로젝트를 위한 agents.md 작성하기

스크레이퍼 (scraper)를 위한 효과적인 agents.md를 구축하는 방법은 다음과 같습니다.

1단계: 파일 생성

프로젝트 루트 (project root)에서:

touch agents.md

2단계: 프론트매터 추가

---
name: product-scraper
description: 제품 데이터를 스크래핑하기 위한 Scrapy spider
...

3단계: 프로젝트 구조 문서화

## Project Structure (프로젝트 구조)

- scrapers/spiders/ - 모든 Scrapy spiders (스파이더)
...

4단계: 명명 규칙 (Naming Conventions) 문서화

## Naming Conventions (명명 규칙)

Spiders: spider_<site_name>.py
...

5단계: 패턴 문서화

당신의 접근 방식을 보여주는 코드 예제를 포함하세요:

## Spider Patterns (스파이더 패턴)

### Basic Spider Structure (기본 스파이더 구조)
...

6단계: 설정 (Configuration) 문서화

## Scrapy Settings (Scrapy 설정)

settings.py의 주요 설정:
...

7단계: 일반적인 작업 (Common Tasks) 문서화

## Common Tasks (일반적인 작업)

### Adding a New Spider (새로운 스파이더 추가)
...

8단계: 의존성 (Dependencies) 문서화

## Dependencies (의존성)

Core (핵심):
...

실제 아이템 구조 (Real Item Structure)

당신의 아이템 (items)이 실제로 어떤 모습인지 문서화하세요:

## Item Format (아이템 형식)

모든 아이템은 다음 구조를 따릅니다:
...

AI 코딩 에이전트와 함께 agents.md를 사용하는 방법

Claude Code와 함께 사용하기

Claude Code는 프로젝트 루트에 있는 agents.md를 자동으로 읽습니다.

그저 도움을 요청하기만 하면 Claude가 당신의 패턴을 따를 것입니다.

예시:
"기존 패턴을 따라 Target.com을 위한 스파이더를 추가해줘"

Claude는 agents.md를 읽습니다. 당신의 명명 규칙(naming conventions), 에러 핸들링(error handling), 스파이더 템플릿(spider template)을 파악합니다. 그리고 완벽하게 부합하는 코드를 생성합니다.

GitHub Copilot과 함께 사용하기

레포지토리(repo) 루트에 agents.md를 생성하세요. GitHub Copilot은 VS Code/GitHub에서 이를 읽습니다.

새로운 스파이더를 타이핑하기 시작하면, Copilot이 당신의 패턴을 따라 자동 완성(autocomplete)을 수행합니다.

Cursor와 함께 사용하기

GitHub Copilot과 동일합니다. Cursor는 agents.md를 자동으로 읽습니다.

OpenAI Codex CLI와 함께 사용하기

Codex를 사용할 때 agents.md를 참조할 수 있습니다.

점진적 공개 (Progressive Disclosure): agents.md 확장하기

작게 시작하세요. 필요할 때마다 더 많이 추가하세요.

버전 1: 최소 구성 (여기서 시작하세요)

---
name: my-scraper
description: 제품 데이터를 위한 Scrapy scraper
...

이것으로 시작하세요. 작동하게 만든 다음, 확장해 나가세요.

버전 2: 패턴 (Patterns)

스파이더 템플릿, 파이프라인 패턴(pipeline patterns), 일반적인 작업들을 추가하세요.

버전 3: 완전체 (Complete)

전체 참조(full reference), 모든 패턴(patterns), 모든 컨벤션(conventions), 트러블슈팅(troubleshooting)을 추가하세요.

버전 4: 고급 (Advanced)

복잡한 패턴(complex patterns), 예외 케이스(edge cases), 성능 팁(performance tips)을 추가하세요.

흔한 실수 (그리고 해결 방법)

실수 1: 너무 김 (Too Long)

5,000단어 분량의 agents.md를 작성합니다. 너무 많습니다. AI는 이를 모두 처리할 수 없습니다.

해결책: 2,000단어 미만으로 유지하세요. 점진적 공개(progressive disclosure) 방식을 사용하세요. 외부 파일을 참조하세요:

"복잡한 스크래핑 시나리오는 docs/advanced-patterns.md를 참조하세요."

실수 2: 너무 모호함 (Too Vague)

"좋은 이름을 사용하세요."

너무 모호합니다. AI는 '좋은 것'이 무엇인지 모릅니다.

해결책: 구체적으로 작성하세요. 예시를 보여주세요.

"Spiders: spider_.py. Classes: Spider. Methods: snake_case."

실수 3: 오래된 정보 (Outdated)

패턴은 업데이트했지만 agents.md를 업데이트하는 것을 잊었습니다.

AI는 파일에 있는 오래된 패턴을 따릅니다.

해결책: 패턴을 변경할 때마다 agents.md를 업데이트하세요. 이를 Git에 커밋하세요.

실수 4: 설명 없이 예시만 있음 (Only Examples, No Explanation)

예시는 보여주지만 맥락(context)이 없습니다.

해결책: 이유를 설명하세요. 예시와 추론(reasoning)을 모두 보여주세요.

실수 5: 너무 많은 지식을 가정함 (Assumes Too Much Knowledge)

"유연성을 위해 kwargs를 사용하는 것을 기억하세요."

신입 개발자들은 이를 이해하지 못합니다.

해결책: 초보자를 위해 설명하세요. 그것이 무엇을 하는지 보여주세요.

팀을 위한 agents.md

여러 개발자가 스크래퍼(scraper)를 작업할 때, agents.md는 매우 중요해집니다.

표준 강제 (Enforcing Standards)

모든 개발자가 동일한 agents.md를 읽습니다. 모두가 동일한 패턴을 따릅니다.

더 이상의 논쟁은 없습니다: "이것을 snake_case로 해야 할까요, CamelCase로 해야 할까요?" 정답은 agents.md에 있습니다.

신입 개발자 온보딩 (Onboarding New Developers)

신입 개발자가 합류합니다. 당신은 이렇게 말합니다: "agents.md를 읽어보세요. 우리가 어떻게 일하는지 설명되어 있습니다."

그들은 파일 하나만 읽으면 됩니다. 이제 즉시 당신의 패턴을 따라 기여할 수 있습니다.

더 빠른 코드 리뷰 (Code Review Faster)

리뷰어는 코드가 agents.md 패턴을 따르는지 확인합니다. 스타일(style)에 관한 코멘트가 줄어듭니다.

포맷팅(formatting)이 아닌 로직(logic)에 집중하세요.

AI를 통한 패턴 강제 (AI Helps Enforce Patterns)

agents.md에 다음 내용을 추가하세요:

"AI는 다음 사항을 확인합니다:

• 모든 메서드(methods)가 snake_case를 사용하는지
• 모든 스파이더(spiders)가 scrapy.Spider를 상속받는지
• 모든 에러가 URL과 함께 로그(log)에 기록되는지
• 모든 아이템(items)이 yield 하기 전에 검증(validate)되는지"

Claude Code에게 도움을 요청하면, Claude Code가 이러한 사항들을 자동으로 확인합니다.

실전 예시: 완성된 agents.md

다음은 이커머스 스크래퍼(e-commerce scraper)를 위한 완성된 agents.md 예시입니다:

---
name: ecommerce-scraper
description: Scrapy spider for scraping product data
...

이것은 완성된 형태의 agents.md입니다. Claude Code가 이를 읽으면 여러분의 프로젝트에 관한 모든 것을 이해하게 됩니다. 모든 제안(suggestion)이 여러분의 패턴(patterns)을 따르게 됩니다.

요약

agents.md는 AI 에이전트(AI agents)에게 여러분의 프로젝트가 어떻게 작동하는지 가르칩니다.

개념:

프로젝트 루트(root)에 위치한 Markdown 파일입니다. YAML 프론트매터(frontmatter)와 Markdown 본문으로 구성됩니다. 패턴(patterns), 컨벤션(conventions), 아키텍처(architecture)를 기술합니다. Claude Code, GitHub Copilot, Cursor에 의해 자동으로 읽힙니다.

중요성:

AI가 여러분의 스타일(style)에 맞는 코드를 작성합니다. AI가 생성한 코드를 다시 작성할 필요가 없습니다. 새로운 개발자의 온보딩(onboarding)이 빨라집니다. 일관된 프로젝트 표준을 유지합니다. 모든 AI 코딩 에이전트(AI coding agents)와 함께 작동합니다.

사용 방법:

1. 프로젝트 루트에 agents.md 생성
2. 여러분의 패턴(spiders, pipelines, naming 등)을 문서화
3. 예시(examples) 추가
4. AI가 이를 자동으로 읽도록 함
5. 자신 있게 도움 요청

모범 사례(Best practices):

2,000단어 이내로 유지하세요. 모호하게 작성하지 말고 구체적으로 작성하세요. 패턴이 변경될 때 업데이트하세요. 점진적 공개(progressive disclosure) 방식을 사용하세요. 단순히 예시만 들지 말고 '왜(why)' 그런지 설명하세요.

팀을 위한 활용:

하나의 agents.md = 모든 팀원이 동일한 이해도를 가짐. 더 빠른 코드 리뷰(code review). 더 쉬운 온보딩. 논쟁 없이 표준을 강제할 수 있음.

여러분은 단순히 스크래퍼를 만드는 것이 아닙니다. AI에게 스크래퍼를 만드는 법을 가르치는 스크래퍼를 만들고 있는 것입니다.

개발의 미래는 인간과 AI가 함께 협력하는 것입니다. agents.md는 AI가 좋은 협업자(collaborator)가 되도록 가르치는 방법입니다.

다음 단계:

1. 다음 프로젝트(또는 기존 프로젝트)에 agents.md 생성
2. 여러분의 패턴을 문서화
3. Claude Code 또는 GitHub Copilot에게 도움 요청
4. AI가 여러분의 스타일을 완벽하게 따르는 것을 확인
5. 패턴이 진화함에 따라 agents.md를 업데이트

패턴을 문서화하는 데 투자하는 시간은 AI에게 도움을 요청할 때마다 배당금처럼 돌아올 것입니다.