오랜만에 남의 저장소를 열었다가 낯선 파일들을 보신 적 있으신가요. README.md 옆에 CLAUDE.md가 있고, AGENTS.md도 보이고, 어떤 곳엔 DESIGN.md까지 있습니다. 죄다 확장자가 .md인데 정체는 잘 모르겠고요.
전부 AI에게 읽히려고 만든 문서입니다. 사람이 아니라요.
몇 해 전만 해도 저장소의 마크다운 파일은 README와 라이선스 정도였습니다. 그런데 AI 코딩 도구가 실무에 들어오면서 “이 프로젝트에선 이렇게 일합니다"를 AI에게도 알려줘야 하는 상황이 됐어요. 매번 채팅창에 같은 설명을 반복하는 대신 파일로 적어두자는 거죠. 그렇게 하나둘 늘어난 게 지금 보이는 그 파일들입니다.
이 글은 그 파일들의 정체를 하나씩 밝힙니다. 각각 누가 읽고, 무엇을 적고, 어디에 두는지요. 잘 쓴 예시를 어디서 구하는지도 함께 정리했습니다.
마크다운 문법 자체가 처음이시라면 마크다운 문법 제대로 쓰기를 먼저 보고 오셔도 좋습니다. 이 글은 문법을 몰라도 읽을 수 있게 썼지만,
#이나-가 뭔지 알고 보면 훨씬 편하거든요.
AI는 왜 하필 마크다운으로 말할까#
파일 하나하나를 보기 전에 짚고 갈 게 있습니다. 세상에 문서 포맷이 그렇게 많은데, 왜 하필 마크다운일까요? 챗봇 답변이 마크다운으로 나오는 것도, AI용 지침 파일이 죄다 .md인 것도 우연이 아닙니다. 이유가 셋 있어요.
첫째, AI가 마크다운을 제일 많이 보고 자랐습니다. 대규모 언어 모델은 인터넷 텍스트로 학습하는데, GitHub의 README와 문서, 개발자 포럼 글 상당수가 마크다운입니다. 모델 입장에서는 모국어에 가까워요.
둘째, 구조를 몇 글자로 표현합니다. 제목·목록·표·코드 블록 같은 구조를 HTML로 쓰면 태그가 열리고 닫히며 글자 수가 몇 배로 붑니다. AI는 주고받는 글자량(토큰)이 곧 비용과 속도라서, 같은 구조를 더 적은 글자로 쓰는 포맷이 유리합니다.
셋째, 어디서든 통합니다. 채팅 화면은 마크다운을 렌더링해 보여주고, 렌더링이 없는 곳에서도 일반 텍스트라 읽을 수는 있습니다. 최악의 경우가 “기호가 좀 보인다” 정도로 방어되는 거죠.
그래서 방향이 역전됐습니다. 지금까지는 사람이 읽을 문서를 마크다운으로 썼다면, 이제는 AI가 읽을 문서도 마크다운으로 씁니다. 여러분 저장소에 하나둘 생기는 그 파일들이 바로 그겁니다.
AI 도구가 읽는 마크다운 파일들 — 정체를 하나씩#
요즘 저장소에서 마주치는 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에는 불러오기 한 줄만 둡니다.
@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가 사람이 가장 많이 손보는 파일입니다. 요구사항은 대체로 명확하고 작업 목록은 설계에서 파생되는데, 설계는 선택지가 여럿이라 판단이 필요하거든요. 실제로 이런 모양입니다.
# 설계 — 회원가입
## 아키텍처
- 인증: 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는 값을 그대로 쓰고, 애매할 땐 이유를 읽고 판단하는 거예요.
---
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에 “60k+ 예시 보기” 링크가 있습니다. 별도 갤러리가 아니라 GitHub 코드 검색으로 실제 저장소의 AGENTS.md를 바로 훑는 방식이에요. 사이트에는 openai/codex, apache/airflow 같은 구체적인 사례도 걸려 있어서 규모 있는 프로젝트가 어떻게 쓰는지 볼 수 있습니다.
검색하면
awesome-agents.md같은 큐레이션 목록도 나오는데, 대표적인 그 저장소는 2025년 10월 이후 갱신이 멈추고 아카이브됐습니다. 지금은 공식 사이트의 코드 검색이 더 최신입니다.
CLAUDE.md 예시 — awesome-claude-code#
Claude Code 쪽은 awesome-claude-code가 사실상 표준 모음집입니다. 별 5만 개가 넘고 지금도 꾸준히 갱신됩니다(최근 한 달만 봐도 열흘 넘게 커밋이 있었어요). CLAUDE.md 예시뿐 아니라 슬래시 커맨드, 훅, 워크플로까지 함께 모여 있어서 “다른 사람들은 어떻게 쓰나"를 한 번에 볼 수 있습니다.
DESIGN.md 예시 — getdesign.md와 awesome-design-md#
디자인 파일은 남의 것을 보는 게 특히 도움이 됩니다. 색을 고르는 안목이 없어도 잘 만든 걸 가져다 고치면 되거든요.
getdesign.md는 DESIGN.md를 모아 보여주는 갤러리입니다. 마음에 드는 스타일을 골라 그대로 받아 쓸 수 있어요. 같은 팀이 만든 awesome-design-md 저장소에는 스트라이프·애플·스포티파이·피그마 같은 브랜드의 디자인 시스템을 분석해 옮긴 파일이 70종 넘게 있습니다. 별이 10만 개를 넘겼는데, 그만큼 “AI가 만든 화면이 다 비슷하다"는 갈증이 컸다는 뜻이겠죠.
형식 자체가 궁금하면 명세 저장소를 보시면 됩니다.
README 디자인 — readme.so와 프로필 템플릿 모음#
README를 예쁘게 만들고 싶다면 readme.so가 편합니다. 필요한 섹션(설치·사용법·라이선스…)을 골라 넣고 채우기만 하면 마크다운이 완성되는 무료 웹 편집기예요. 오픈소스이기도 합니다.
GitHub 프로필 README(내 계정 이름과 똑같은 이름의 공개 저장소를 만들고 README.md를 넣으면 프로필 상단에 뜨는 그것)를 꾸미려면 Awesome-Profile-README-templates 같은 모음집이나 프로필 README 생성기가 있습니다. 기술 스택 배지, 방문자 카운터 같은 걸 클릭 몇 번으로 붙일 수 있어요.
배지는 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).
# 프로젝트 작업 지침
## 프로젝트 소개
회원제 독서 모임 웹앱. Next.js(App Router) + Supabase.
## 자주 쓰는 명령
- 개발 서버: `npm run dev`
- 테스트: `npm test`
- 빌드 확인: `npm run build`
## 규칙
- 컴포넌트는 `src/components/`에, 페이지는 `src/app/`에 둔다
- 스타일은 Tailwind만 사용 (CSS 파일 새로 만들지 말 것)
- 커밋 메시지는 한국어로
## 하지 말 것
- `main` 브랜치에 직접 커밋 금지
- `.env` 파일 수정·출력 금지비결 같은 건 없습니다. 새 팀원이 첫날 물어볼 것들을 미리 적는다고 생각하면 내용이 저절로 나와요. 그리고 AI가 뭔가 잘못했을 때마다 “하지 말 것"에 한 줄씩 쌓아가면 됩니다. 이 블로그의 규약 파일도 그렇게 자랐어요. 처음부터 완벽한 지침서를 쓴 게 아니라, 사고가 날 때마다 재발 방지 조항이 한 줄씩 늘어난 결과물입니다.
블로그나 문서 사이트를 운영한다면 llms.txt는 이런 모양입니다.
# 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>이 되죠. 구조는 문법이 공짜로 만들어주지만, 그 안에 들어갈 내용은 아무도 대신 채워주지 않습니다. 이 이야기는 마크다운 문법 제대로 쓰기의 접근성 절에서 자세히 다뤘어요.
그래서 제가 쓰는 방법은 규칙 파일에 접근성 항목을 적어두는 것입니다. 앞에서 만들어본 그 파일(CLAUDE.md든 AGENTS.md든)에 이런 줄을 넣어두면 매번 지시하지 않아도 됩니다.
## 접근성 규칙
- 이미지에는 화면에 실제로 보이는 것을 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가 쓴 결과물의 접근성은 규칙 파일에 항목으로 적어 관리하고, 마지막 확인은 사람이 한다.
질문으로 다시 보기#
CLAUDE.md와 AGENTS.md는 뭐가 다른가요?
llms.txt는 꼭 만들어야 하나요?
CONTRIBUTING.md는 어디에 두나요?
design.md는 무엇이고 CLAUDE.md와 어떻게 다른가요?
DESIGN.md와 design.md는 같은 파일인가요?
이어서 읽기#
- 마크다운 문법 제대로 쓰기 — 자주 밟는 함정과 접근성까지 — 문법 아홉 가지, 줄바꿈·굵게 깨짐 같은 함정, 편집기 추천, 그리고 마크다운이 곧 시맨틱 HTML인 이유
참고 자료#
AI용 파일
- AGENTS.md 공식 사이트 — 6만 개 저장소의 실제 예시로 이어짐
- Claude Code 메모리(CLAUDE.md) 공식 문서
- awesome-claude-code — CLAUDE.md·커맨드·워크플로 모음
- DESIGN.md 형식 명세 — 구글 랩스, 알파
- getdesign.md · awesome-design-md — DESIGN.md 갤러리와 브랜드별 모음
- Kiro 스펙 문서 — requirements·design·tasks 세 파일 구조
- GitHub Spec Kit — 스펙 주도 개발 도구 모음
- llms.txt 제안 문서
README·GitHub 문서
- readme.so — 섹션을 골라 만드는 README 편집기
- Awesome-Profile-README-templates — 프로필 README 예시 모음
- shields.io — 배지 생성
- GitHub 기여 가이드라인 설정 문서