# AI 시대의 마크다운 — CLAUDE.md·AGENTS.md·DESIGN.md

> 저장소에 늘어나는 CLAUDE.md·AGENTS.md·DESIGN.md·llms.txt는 각각 뭐 하는 파일인지, 누가 읽고 무엇을 적는지, 잘 쓴 예시는 어디서 구하는지, 스펙 주도 개발의 design.md까지 초보 눈높이로 정리했습니다.

**Published:** 2026-08-15 | **Updated:** 2026-08-15

---


오랜만에 남의 저장소를 열었다가 낯선 파일들을 보신 적 있으신가요. `README.md` 옆에 `CLAUDE.md`가 있고, `AGENTS.md`도 보이고, 어떤 곳엔 `DESIGN.md`까지 있습니다. 죄다 확장자가 `.md`인데 정체는 잘 모르겠고요.

전부 **AI에게 읽히려고 만든 문서**입니다. 사람이 아니라요.

몇 해 전만 해도 저장소의 마크다운 파일은 README와 라이선스 정도였습니다. 그런데 AI 코딩 도구가 실무에 들어오면서 "이 프로젝트에선 이렇게 일합니다"를 **AI에게도 알려줘야** 하는 상황이 됐어요. 매번 채팅창에 같은 설명을 반복하는 대신 파일로 적어두자는 거죠. 그렇게 하나둘 늘어난 게 지금 보이는 그 파일들입니다.

이 글은 그 파일들의 정체를 하나씩 밝힙니다. 각각 누가 읽고, 무엇을 적고, 어디에 두는지요. 잘 쓴 예시를 어디서 구하는지도 함께 정리했습니다.

> 마크다운 문법 자체가 처음이시라면 [마크다운 문법 제대로 쓰기]({{< relref "/posts/markdown-syntax-guide" >}})를 먼저 보고 오셔도 좋습니다. 이 글은 문법을 몰라도 읽을 수 있게 썼지만, `#`이나 `-`가 뭔지 알고 보면 훨씬 편하거든요.

## AI는 왜 하필 마크다운으로 말할까

파일 하나하나를 보기 전에 짚고 갈 게 있습니다. 세상에 문서 포맷이 그렇게 많은데, 왜 하필 마크다운일까요? 챗봇 답변이 마크다운으로 나오는 것도, AI용 지침 파일이 죄다 `.md`인 것도 우연이 아닙니다. 이유가 셋 있어요.

첫째, **AI가 마크다운을 제일 많이 보고 자랐습니다.** 대규모 언어 모델은 인터넷 텍스트로 학습하는데, GitHub의 README와 문서, 개발자 포럼 글 상당수가 마크다운입니다. 모델 입장에서는 모국어에 가까워요.

둘째, **구조를 몇 글자로 표현합니다.** 제목·목록·표·코드 블록 같은 구조를 HTML로 쓰면 태그가 열리고 닫히며 글자 수가 몇 배로 붑니다. AI는 주고받는 글자량(토큰)이 곧 비용과 속도라서, 같은 구조를 더 적은 글자로 쓰는 포맷이 유리합니다.

셋째, **어디서든 통합니다.** 채팅 화면은 마크다운을 렌더링해 보여주고, 렌더링이 없는 곳에서도 일반 텍스트라 읽을 수는 있습니다. 최악의 경우가 "기호가 좀 보인다" 정도로 방어되는 거죠.

그래서 방향이 역전됐습니다. 지금까지는 사람이 읽을 문서를 마크다운으로 썼다면, 이제는 **AI가 읽을 문서도 마크다운으로 씁니다**. 여러분 저장소에 하나둘 생기는 그 파일들이 바로 그겁니다.

## AI 도구가 읽는 마크다운 파일들 — 정체를 하나씩

요즘 저장소에서 마주치는 AI용 마크다운 파일들을 하나씩 보겠습니다. 전체 지도를 먼저 그려두면 따라오기 쉬워요.

{{< img src="images/contents/ai-md-files-map.png" alt="마크다운 파일 지도 - 저장소에는 README.md(사람과 AI 모두), CLAUDE.md(Claude Code), AGENTS.md(여러 에이전트 공통), 도구별 규칙 파일, 그리고 CONTRIBUTING.md 같은 사람 기여자용 문서가 함께 놓이고, 웹사이트에는 llms.txt가 AI에게 주는 안내판으로 놓입니다" >}}

### README.md — 원래 있던 터줏대감

새로운 파일은 아니지만 역할이 하나 늘었습니다. 원래 사람에게 프로젝트를 소개하는 파일인데, AI 코딩 도구도 **프로젝트 파악의 출발점으로 README를 읽습니다**. "이 프로젝트가 뭐 하는 물건인지"를 AI에게 설명하는 첫 문서가 된 거죠. README가 부실하면 사람도 헤매고 AI도 헤맵니다.

### CLAUDE.md — Claude Code에게 주는 작업 지침서

**CLAUDE.md**는 Anthropic의 AI 코딩 도구인 Claude Code가 세션을 시작할 때 자동으로 읽는 파일입니다. 프로젝트 루트에 두면 그 프로젝트의 규칙이 되고, 홈 디렉터리(`~/.claude/CLAUDE.md`)에 두면 모든 프로젝트에 적용되는 개인 규칙이 됩니다.

뭘 적는 파일이냐면, **같이 일하게 된 동료에게 알려줄 것들**을 적습니다. 빌드는 어떤 명령으로 하는지, 절대 하면 안 되는 게 뭔지, 코드 스타일은 어떤지요. 이 블로그도 "Hugo는 asdf로 관리하니 brew로 설치하지 말 것" 같은 규칙을 적어두고 씁니다. 한 번 겪은 함정을 파일에 남겨두면 다음 세션의 AI는 그 함정을 알고 시작하거든요. 덕분에 같은 실수가 반복되지 않습니다.

### AGENTS.md — 도구를 가리지 않는 공통 지침서

CLAUDE.md의 아쉬운 점은 이름 그대로 Claude 전용이라는 겁니다. Cursor를 쓰는 팀원, Codex를 쓰는 팀원이 섞여 있으면 도구마다 지침 파일을 따로 둬야 할까요?

그 문제에 대한 답이 **AGENTS.md**입니다. 특정 회사에 묶이지 않은 공통 규약으로, "에이전트를 위한 README"라고 소개돼요. OpenAI Codex를 비롯해 Cursor, VS Code, GitHub Copilot, Google Jules 등 20종이 넘는 도구가 이 파일을 읽습니다. 적는 내용은 CLAUDE.md와 같은 성격입니다 — 빌드·테스트 방법, 코딩 규약, 주의사항.

규모가 궁금하실 텐데, 공식 사이트 기준 **6만 개가 넘는 오픈소스 프로젝트**가 쓰고 있습니다. 2026년 현재 이 규약은 리눅스 재단 산하 Agentic AI Foundation이 관리해요. 한 회사의 실험이 아니라 업계 공용 규격으로 자리를 잡아가는 중입니다.

그럼 둘 다 만들어야 할까요? 여기서 알아둘 게 있습니다. **Claude Code는 AGENTS.md를 읽지 않습니다.** CLAUDE.md만 읽어요. 그래서 두 파일을 따로 관리하면 내용이 어긋나기 시작합니다.

공식 문서가 권하는 방법은 **한쪽에 본문을 쓰고 다른 쪽이 그걸 불러오게** 하는 것입니다. AGENTS.md에 내용을 적고, CLAUDE.md에는 불러오기 한 줄만 둡니다.

```markdown
@AGENTS.md

## Claude Code 전용

`src/billing/` 아래를 고칠 땐 계획 모드를 쓸 것.
```

`@파일명`은 그 파일을 통째로 끌어오는 문법입니다. 아래에 Claude 전용 규칙을 덧붙일 수도 있고요. 덧붙일 게 없으면 심볼릭 링크(`ln -s AGENTS.md CLAUDE.md`)로 아예 같은 파일을 보게 해도 됩니다.

이 블로그도 이 글을 쓰다가 그렇게 바꿨습니다. 규약 본문은 전부 `AGENTS.md`에 있고, `CLAUDE.md`에는 `@AGENTS.md` 한 줄과 "수정은 AGENTS.md에서 하세요"라는 주석만 남겨뒀어요. 파일이 둘인데 관리할 곳은 하나입니다.

### 도구별 전용 파일 — .cursor/rules와 copilot-instructions.md

같은 목적의 도구별 변형도 있습니다. Cursor는 `.cursor/rules/` 폴더의 규칙 파일을, GitHub Copilot은 `.github/copilot-instructions.md`를 읽습니다. 형식이 조금씩 다를 뿐 "AI에게 주는 프로젝트 지침"이라는 본질은 같아요. 팀이 쓰는 도구가 정해져 있다면 그 도구의 파일 하나만 관리해도 충분합니다.

### requirements.md·design.md·tasks.md — 코딩 전에 합의하는 문서

지금까지가 "이 프로젝트에선 이렇게 일한다"는 상시 규칙이었다면, 이건 **기능 하나를 만들 때마다 새로 쓰는** 문서들입니다.

배경부터 말씀드릴게요. AI에게 "로그인 기능 만들어줘" 하면 곧장 코드가 쏟아집니다. 그런데 다 만들고 보니 소셜 로그인을 원했는데 이메일 로그인을 짰다거나, 세션 방식이 우리 구조와 안 맞는 일이 생기죠. 200줄을 버리고 다시 시작합니다. 이걸 막으려고 **만들기 전에 문서로 합의하고 시작하자**는 방식이 나왔는데, 이걸 **스펙 주도 개발**(Spec-Driven Development)이라고 부릅니다.

문서는 보통 셋으로 나눕니다. 순서가 곧 질문의 순서예요.

| 파일 | 답하는 질문 | 담기는 것 |
|---|---|---|
| `requirements.md` | 무엇을, 왜 | 사용자 스토리, 완료 조건 |
| `design.md` | 어떻게 만들 것인가 | 아키텍처, 데이터 흐름, 에러 처리, 테스트 전략 |
| `tasks.md` | 어떤 순서로 | 쪼갠 작업 목록, 각 작업의 결과물 |

이 중 **`design.md`**\ 가 사람이 가장 많이 손보는 파일입니다. 요구사항은 대체로 명확하고 작업 목록은 설계에서 파생되는데, 설계는 선택지가 여럿이라 판단이 필요하거든요. 실제로 이런 모양입니다.

```markdown
# 설계 — 회원가입

## 아키텍처

- 인증: Supabase Auth (이메일 + 매직 링크)
- 세션: 서버 컴포넌트에서 쿠키로 검증, 클라이언트 상태 저장 안 함
- 프로필: `profiles` 테이블, `auth.users.id`를 외래키로

## 데이터 흐름

1. 이메일 입력 → Supabase에 매직 링크 요청
2. 메일 링크 클릭 → `/auth/callback`에서 세션 교환
3. 최초 로그인이면 `profiles` 행 생성 후 온보딩으로
4. 이미 있으면 원래 가던 페이지로

## 에러 처리

| 상황 | 사용자에게 | 기록 |
|---|---|---|
| 링크 만료 | "링크가 만료됐어요. 다시 보내드릴까요?" + 재발송 버튼 | info |
| 이미 가입된 메일 | 로그인 화면으로 안내 (가입 여부는 노출하지 않음) | info |
| Supabase 응답 없음 | "잠시 후 다시 시도해 주세요" | error + 알림 |

## 접근성

- 이메일 입력에 `<label>` 연결, `autocomplete="email"`
- 오류 메시지는 입력란과 `aria-describedby`로 연결
- 발송 완료는 `aria-live="polite"`로 알림 (화면 전환 없음)

## 테스트 전략

- 단위: 콜백 핸들러의 세션 교환 분기
- E2E: 최초 가입 / 재로그인 / 만료 링크 세 흐름
- 접근성: 회원가입 흐름 axe 검사, 키보드만으로 완주
```

이걸 먼저 써두면 AI가 코드를 짜기 전에 **"이 방향이 맞나"를 사람이 확인할 지점**이 생깁니다. 위 문서에서 "세션을 클라이언트에 저장하지 않는다" 한 줄이면, 그다음 나올 코드의 절반이 결정되죠.

접근성 항목을 설계 단계에 끼워 넣은 것도 의도한 겁니다. 나중에 덧붙이는 것보다 처음부터 적어두는 쪽이 훨씬 쌉니다. 다 만든 뒤에 "여기 라벨이 없네요" 소리를 듣는 것과, 만들기 전에 한 줄 적어두는 것의 차이예요.

> **파일 이름은 도구마다 다릅니다.** AWS의 **Kiro**는 `requirements.md`·`design.md`·`tasks.md` 셋으로 나누고 `.kiro/specs/{기능이름}/` 아래에 둡니다. GitHub의 **Spec Kit**은 `spec.md`·`plan.md`·`tasks.md`로 부르고요(설계에 해당하는 게 `plan.md`입니다). 도구를 안 써도 상관없습니다 — 손으로 하나 써서 AI에게 읽히는 것만으로도 효과가 있거든요.

### DESIGN.md — 화면 디자인을 AI에게 넘겨주는 파일

여기서 헷갈리기 딱 좋은 지점이 있어 먼저 정리하고 갈게요. **이름이 거의 같은데 완전히 다른 파일이 하나 더 있습니다.**

| 구분 | `design.md` (방금 본 것) | `DESIGN.md` (지금 볼 것) |
|---|---|---|
| 담는 것 | 기능 하나의 **기술 설계** | 제품 전체의 **시각 정체성** |
| 예시 항목 | 아키텍처, 데이터 흐름, 에러 처리 | 색상, 서체, 간격, 컴포넌트 |
| 나온 곳 | Kiro의 스펙 3종 중 하나 | Google Labs가 공개한 형식 명세 |
| 쓰는 주기 | 기능마다 새로 | 한 번 쓰고 계속 |

문제의식은 이렇습니다. AI에게 화면을 만들어달라고 하면 결과가 늘 **비슷하게 생깁니다.** 둥근 모서리에 보라색 그라데이션, 어디서 본 듯한 카드 배치요. 기능은 맞는데 우리 서비스처럼 안 보이죠. 매번 "우리 메인 색은 이거고 버튼은 이렇게"를 설명하기도 지칩니다.

**DESIGN.md**는 그걸 파일 하나로 넘겨주자는 발상입니다. 구조가 재미있는데, **위쪽 YAML에는 기계가 읽을 값**을 적고 **아래 마크다운에는 사람이 읽을 이유**를 적습니다. AI는 값을 그대로 쓰고, 애매할 땐 이유를 읽고 판단하는 거예요.

```markdown
---
version: "alpha"
name: 독서 모임
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#FFFFFF"
---

## Overview

책을 오래 붙잡고 읽게 만드는 것이 목표입니다. 화면은 종이에 가깝게,
장식은 최소로. 시선을 끄는 색은 한 곳(주요 행동 버튼)에만 씁니다.

## Colors

`tertiary`(#B8422E)는 강조색입니다. 한 화면에 한 번만 쓰세요.
본문 글자는 항상 `primary`를 배경 흰색 위에 올립니다.

## Do's and Don'ts

- 강조색을 본문 글자에 쓰지 않습니다 — 흰 배경에서 대비가 4.5:1에 못 미칩니다
- 카드에 그림자를 겹치지 않습니다. 깊이는 한 단계까지
- 버튼 안에 아이콘만 넣지 않습니다. 글자를 함께 둡니다
```

마크다운 본문은 **Overview → Colors → Typography → Layout → Elevation & Depth → Shapes → Components → Do's and Don'ts** 순서로 쓰도록 명세에 정해져 있습니다. 다 채울 필요는 없고, 있는 것만 순서대로 두면 됩니다.

접근성 관점에서 이 파일이 반가운 이유가 있습니다. **"이 색은 본문에 쓰지 마세요, 대비가 부족합니다" 같은 판단을 토큰 옆에 적어둘 수 있거든요.** AI는 색 이름만 보면 그게 대비를 통과하는지 모릅니다. 다 만든 뒤에 대비비 검사에서 무더기로 걸리는 것보다, 쓰지 말아야 할 조합을 미리 적어두는 쪽이 훨씬 쌉니다.

> 이 명세는 2026년 4월에 공개됐고 아직 **알파 단계**입니다. 명세 자체가 "성숙해지면서 바뀔 수 있다"고 밝히고 있으니, 지금 쓰신다면 형식이 변할 수 있다는 걸 감안하세요.

### llms.txt — 웹사이트가 AI에게 세우는 안내판

지금까지는 저장소 안 파일이었다면, **llms.txt**는 웹사이트가 두는 파일입니다. 사이트 최상위 경로(`/llms.txt`)에 마크다운으로 "우리 사이트의 핵심 문서는 이것이고, 여기에 있다"를 정리해두는 규약이에요. 2024년에 제안됐고, 웹페이지의 광고·메뉴·스크립트를 걷어내고 알맹이만 AI에게 주자는 취지입니다.

이름은 `robots.txt`를 닮았지만 방향이 반대입니다. robots.txt가 "여긴 들어오지 마세요"라면, llms.txt는 "읽으실 거면 이쪽이 정리본입니다"거든요.

한 가지는 분명히 해둘게요. **llms.txt는 아직 제안 단계의 규약입니다.** 제러미 하워드(Jeremy Howard)가 2024년 9월에 초안을 내놨고, 2026년 8월에도 v2로 손질될 만큼 아직 다듬어지는 중이에요. 주요 AI 서비스가 이 파일을 실제로 읽어간다는 보장은 없고, 채택 여부는 서비스마다 다릅니다. 문서 사이트라면 만들어둘 가치가 있지만, "없으면 AI 검색에서 불이익"같은 이야기는 현재로선 근거가 없습니다.

### 한눈에 정리

| 파일 | 누가 읽나 | 어디에 두나 | 무엇을 적나 |
|---|---|---|---|
| README.md | 사람 + AI 전부 | 저장소 루트 | 프로젝트 소개, 시작 방법 |
| CLAUDE.md | Claude Code | 저장소 루트, `~/.claude/` | 프로젝트 규칙, 명령어, 금지사항 |
| AGENTS.md | Codex·Cursor·Jules 등 | 저장소 루트 | CLAUDE.md와 같은 성격 (공통 규약) |
| .cursor/rules | Cursor | `.cursor/` 폴더 | Cursor 전용 규칙 |
| copilot-instructions.md | GitHub Copilot | `.github/` 폴더 | Copilot 전용 규칙 |
| design.md 등 | 사람 + AI | 기능별 폴더 | 기능 하나의 기술 설계 (만들 때마다 새로) |
| DESIGN.md | AI 코딩 도구 | 저장소 루트 | 색·서체·간격 등 시각 정체성 |
| llms.txt | AI 크롤러·챗봇 | 웹사이트 `/llms.txt` | 사이트 핵심 문서 목록 |

위쪽 넷은 **한 번 써두고 계속 쓰는** 규칙이고, `design.md`는 **기능마다 새로 쓰는** 설계 문서라는 차이가 있습니다. 처음부터 다 만들 필요는 전혀 없어요. 쓰는 도구의 파일 하나면 시작으로 충분합니다.

## 예시는 어디서 보나 — 공유 사이트와 모음집

빈 파일 앞에서 막막할 때 가장 빠른 길은 잘 쓴 남의 것을 보는 겁니다. 종류별로 어디를 봐야 하는지 정리했어요.

### AGENTS.md 예시 — 공식 사이트의 코드 검색

[agents.md](https://agents.md/)에 "60k+ 예시 보기" 링크가 있습니다. 별도 갤러리가 아니라 **GitHub 코드 검색으로 실제 저장소의 AGENTS.md를 바로 훑는** 방식이에요. 사이트에는 `openai/codex`, `apache/airflow` 같은 구체적인 사례도 걸려 있어서 규모 있는 프로젝트가 어떻게 쓰는지 볼 수 있습니다.

> 검색하면 `awesome-agents.md` 같은 큐레이션 목록도 나오는데, 대표적인 그 저장소는 2025년 10월 이후 갱신이 멈추고 아카이브됐습니다. 지금은 공식 사이트의 코드 검색이 더 최신입니다.

### CLAUDE.md 예시 — awesome-claude-code

Claude Code 쪽은 [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code)가 사실상 표준 모음집입니다. 별 5만 개가 넘고 지금도 꾸준히 갱신됩니다(최근 한 달만 봐도 열흘 넘게 커밋이 있었어요). CLAUDE.md 예시뿐 아니라 슬래시 커맨드, 훅, 워크플로까지 함께 모여 있어서 "다른 사람들은 어떻게 쓰나"를 한 번에 볼 수 있습니다.

### DESIGN.md 예시 — getdesign.md와 awesome-design-md

디자인 파일은 남의 것을 보는 게 특히 도움이 됩니다. 색을 고르는 안목이 없어도 잘 만든 걸 가져다 고치면 되거든요.

[getdesign.md](https://getdesign.md/)는 DESIGN.md를 모아 보여주는 갤러리입니다. 마음에 드는 스타일을 골라 그대로 받아 쓸 수 있어요. 같은 팀이 만든 [awesome-design-md](https://github.com/VoltAgent/awesome-design-md) 저장소에는 스트라이프·애플·스포티파이·피그마 같은 브랜드의 디자인 시스템을 분석해 옮긴 파일이 70종 넘게 있습니다. 별이 10만 개를 넘겼는데, 그만큼 "AI가 만든 화면이 다 비슷하다"는 갈증이 컸다는 뜻이겠죠.

형식 자체가 궁금하면 [명세 저장소](https://github.com/google-labs-code/design.md)를 보시면 됩니다.

### README 디자인 — readme.so와 프로필 템플릿 모음

README를 예쁘게 만들고 싶다면 [readme.so](https://readme.so/)가 편합니다. 필요한 섹션(설치·사용법·라이선스…)을 골라 넣고 채우기만 하면 마크다운이 완성되는 무료 웹 편집기예요. 오픈소스이기도 합니다.

GitHub **프로필 README**(내 계정 이름과 똑같은 이름의 **공개** 저장소를 만들고 README.md를 넣으면 프로필 상단에 뜨는 그것)를 꾸미려면 [Awesome-Profile-README-templates](https://github.com/kautukkundan/Awesome-Profile-README-templates) 같은 모음집이나 [프로필 README 생성기](https://rahuldkjain.github.io/gh-profile-readme-generator/)가 있습니다. 기술 스택 배지, 방문자 카운터 같은 걸 클릭 몇 번으로 붙일 수 있어요.

배지는 [shields.io](https://shields.io/)에서 만듭니다. 빌드 상태나 버전 같은 정보를 이미지 링크 한 줄로 넣는 서비스인데, README에서 자주 보는 그 알록달록한 딱지들이 대부분 여기서 나옵니다.

> 한 가지만 덧붙일게요. 배지를 줄줄이 붙이는 건 **접근성 면에서는 조심할 부분**입니다. 배지는 결국 이미지라서 스크린 리더는 alt 텍스트만 읽는데, 열 개가 연달아 있으면 정작 프로젝트 설명에 닿기 전에 지칩니다. 꼭 필요한 것만 남기고 alt를 채워주세요.

## GitHub 저장소에 두는 마크다운 파일들

AI용 파일 이야기를 했으니, 원래부터 있던 **사람용 파일**들도 짚고 갈게요. GitHub은 공개 저장소를 평가하는 "커뮤니티 프로필" 체크리스트를 두고 있는데, 거기 들어가는 것들입니다.

| 파일 | 무엇을 적나 | 언제 보이나 |
|---|---|---|
| `README.md` | 프로젝트 소개, 설치·사용법 | 저장소 첫 화면 |
| `CONTRIBUTING.md` | 기여 방법, PR 규칙, 개발 환경 | 이슈·PR 열 때 링크로 안내 |
| `CODE_OF_CONDUCT.md` | 커뮤니티 행동 규범 | 저장소 사이드바 |
| `SECURITY.md` | 취약점 신고 창구·정책 | Security 탭 |
| `LICENSE` | 이용 허락 조건 | 저장소 사이드바 |
| `CHANGELOG.md` | 버전별 변경 이력 | 관례상 루트 (GitHub 공식 항목은 아님) |
| `.github/ISSUE_TEMPLATE/` | 이슈 작성 양식 | 이슈 새로 열 때 |

이 중 **CONTRIBUTING.md**가 실제로 일을 가장 많이 합니다. 누군가 이슈나 PR을 열려고 하면 GitHub이 이 문서 링크를 먼저 보여주거든요. "테스트는 이렇게 돌리세요, 커밋 메시지는 이런 형식입니다" 같은 걸 적어두면 리뷰에서 같은 말을 반복할 일이 줄어듭니다.

두는 위치는 세 곳이 인정됩니다 — 저장소 루트, `.github/` 폴더, `docs/` 폴더. 여러 곳에 있으면 `.github` → 루트 → `docs` 순으로 우선합니다. 루트가 지저분해지는 게 싫으면 `.github/`에 몰아넣으면 돼요.

눈치채셨을지 모르겠는데, **CONTRIBUTING.md와 AGENTS.md는 하는 일이 거의 같습니다.** 하나는 사람 기여자에게, 하나는 AI 에이전트에게 "이 프로젝트에선 이렇게 일합니다"를 알려주는 문서죠. 그래서 요즘은 둘 다 두고 서로를 참조하게 만드는 저장소가 늘고 있습니다. 신입 사원 안내서를 사람용과 로봇용으로 각각 뽑아두는 셈이에요.

## 직접 만들어보기 — 5분이면 됩니다

읽기만 하면 남의 얘기니, 하나 만들어보죠. AI 코딩 도구를 쓰고 있다면 프로젝트 루트에 이런 파일을 만들어보세요. 파일 이름은 쓰는 도구에 맞추면 됩니다(Claude Code면 `CLAUDE.md`, 그 외엔 `AGENTS.md`).

```markdown
# 프로젝트 작업 지침

## 프로젝트 소개

회원제 독서 모임 웹앱. Next.js(App Router) + Supabase.

## 자주 쓰는 명령

- 개발 서버: `npm run dev`
- 테스트: `npm test`
- 빌드 확인: `npm run build`

## 규칙

- 컴포넌트는 `src/components/`에, 페이지는 `src/app/`에 둔다
- 스타일은 Tailwind만 사용 (CSS 파일 새로 만들지 말 것)
- 커밋 메시지는 한국어로

## 하지 말 것

- `main` 브랜치에 직접 커밋 금지
- `.env` 파일 수정·출력 금지
```

비결 같은 건 없습니다. **새 팀원이 첫날 물어볼 것들을 미리 적는다**고 생각하면 내용이 저절로 나와요. 그리고 AI가 뭔가 잘못했을 때마다 "하지 말 것"에 한 줄씩 쌓아가면 됩니다. 이 블로그의 규약 파일도 그렇게 자랐어요. 처음부터 완벽한 지침서를 쓴 게 아니라, 사고가 날 때마다 재발 방지 조항이 한 줄씩 늘어난 결과물입니다.

블로그나 문서 사이트를 운영한다면 llms.txt는 이런 모양입니다.

```markdown
# Codeslog

> 웹 접근성과 프론트엔드 개발을 다루는 기술 블로그.

## 주요 문서

- [프론트엔드 테스트 시리즈](https://www.codeslog.com/series/...): 테스트 입문부터 CI까지 22편
- [WCAG 3.0 시리즈](https://www.codeslog.com/series/...): 차기 접근성 표준 해설
```

첫 줄 `#`에 사이트 이름, `>`에 한 줄 소개, 그 아래 핵심 링크 목록. 구조가 곧 규약입니다.

## AI가 쓴 마크다운은 누가 검토하나

파일을 다 만들었으니 마지막으로 한 가지만 짚고 마치겠습니다. 이 파일들은 AI에게 **무엇을 만들지**를 알려주지만, AI가 내놓은 결과가 맞는지는 여전히 사람이 봐야 합니다. 특히 눈에 잘 안 띄는 영역이 그렇습니다.

AI는 마크다운 문법은 정확하게 씁니다. 제목·목록·표 구조는 대체로 깔끔해요. 문제는 **판단이 필요한 부분**입니다. 이미지 대체 텍스트에 무엇을 적어야 맥락이 맞는지, 이 링크 텍스트가 목적지를 설명하는지, 이 이미지가 장식인지 정보인지는 그 화면을 아는 사람만 알 수 있거든요. AI가 만든 대체 텍스트가 문법적으로는 멀쩡한데 정작 그림에 없는 내용을 적는 일이 실제로 생깁니다.

마크다운은 변환되면 **시맨틱 HTML**이 됩니다. `##`은 `<h2>`가 되고 표는 `<th>`가 있는 `<table>`이 되죠. 구조는 문법이 공짜로 만들어주지만, 그 안에 들어갈 내용은 아무도 대신 채워주지 않습니다. 이 이야기는 [마크다운 문법 제대로 쓰기]({{< relref "/posts/markdown-syntax-guide" >}})의 접근성 절에서 자세히 다뤘어요.

그래서 제가 쓰는 방법은 **규칙 파일에 접근성 항목을 적어두는 것**입니다. 앞에서 만들어본 그 파일(`CLAUDE.md`든 `AGENTS.md`든)에 이런 줄을 넣어두면 매번 지시하지 않아도 됩니다.

```markdown
## 접근성 규칙

- 이미지에는 화면에 실제로 보이는 것을 alt로 적는다. 장식용이면 alt를 비운다
- 파일명을 alt로 쓰지 않는다
- 링크 텍스트에 목적지를 담는다 ("여기", "더보기" 금지)
- 제목 단계(#, ##, ###)를 건너뛰지 않는다
- 표의 좌상단 제목 칸을 비우지 않는다
```

이 블로그의 규약 파일에도 비슷한 항목이 들어 있고, 덕분에 초안 단계에서 걸리는 일이 크게 줄었습니다. 물론 마지막 확인은 사람이 합니다. 규칙 파일과 자동 검사는 예선이고, 본선은 여전히 사람 몫이에요.

**AI에게 접근성을 가르치는 것도 결국 마크다운 파일로 한다** — 이 글에서 본 파일들이 하는 일이 딱 그겁니다.

## 한 장 요약

- 저장소에 늘어나는 `.md` 파일들은 **AI에게 읽히려고 만든 문서**다. 매번 채팅으로 설명하는 대신 파일로 적어둔 것.
- AI가 마크다운을 쓰는 이유: 학습 데이터에 많고, 구조를 적은 글자로 표현하고, 어디서든 통해서.
- **CLAUDE.md**(Claude Code)·**AGENTS.md**(공통 규약, 리눅스 재단 산하 관리)는 상시 프로젝트 지침 — "새 팀원 첫날 안내"를 적는다.
- Claude Code는 **AGENTS.md를 읽지 않는다.** 둘 다 쓸 땐 AGENTS.md에 본문, CLAUDE.md에 `@AGENTS.md` 한 줄.
- **design.md**(소문자)는 기능마다 새로 쓰는 **기술 설계**, **DESIGN.md**(대문자, 구글 명세)는 색·서체를 넘기는 **시각 정체성**. 이름만 닮았을 뿐 다른 파일이다.
- **llms.txt**는 웹사이트가 AI에게 주는 핵심 문서 안내판 — 아직 제안 단계, 의무 아님.
- 예시는 agents.md의 코드 검색, **awesome-claude-code**, **getdesign.md**, README는 **readme.so**.
- GitHub 사람용 파일은 README·**CONTRIBUTING**·CODE_OF_CONDUCT·SECURITY·LICENSE. 루트·`.github/`·`docs/` 중 아무 데나.
- AI가 쓴 결과물의 접근성은 **규칙 파일에 항목으로 적어** 관리하고, 마지막 확인은 사람이 한다.

{{< faq >}}

## 이어서 읽기

- [마크다운 문법 제대로 쓰기 — 자주 밟는 함정과 접근성까지]({{< relref "/posts/markdown-syntax-guide" >}}) — 문법 아홉 가지, 줄바꿈·굵게 깨짐 같은 함정, 편집기 추천, 그리고 마크다운이 곧 시맨틱 HTML인 이유

## 참고 자료

**AI용 파일**

- [AGENTS.md 공식 사이트](https://agents.md/) — 6만 개 저장소의 실제 예시로 이어짐
- [Claude Code 메모리(CLAUDE.md) 공식 문서](https://code.claude.com/docs/en/memory)
- [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) — CLAUDE.md·커맨드·워크플로 모음
- [DESIGN.md 형식 명세](https://github.com/google-labs-code/design.md) — 구글 랩스, 알파
- [getdesign.md](https://getdesign.md/) · [awesome-design-md](https://github.com/VoltAgent/awesome-design-md) — DESIGN.md 갤러리와 브랜드별 모음
- [Kiro 스펙 문서](https://kiro.dev/docs/specs/) — requirements·design·tasks 세 파일 구조
- [GitHub Spec Kit](https://github.com/github/spec-kit) — 스펙 주도 개발 도구 모음
- [llms.txt 제안 문서](https://llmstxt.org/)

**README·GitHub 문서**

- [readme.so](https://readme.so/) — 섹션을 골라 만드는 README 편집기
- [Awesome-Profile-README-templates](https://github.com/kautukkundan/Awesome-Profile-README-templates) — 프로필 README 예시 모음
- [shields.io](https://shields.io/) — 배지 생성
- [GitHub 기여 가이드라인 설정 문서](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors)