예상 읽기 시간: 약 6분
MD 파일 AI 지침을 처음 만났을 때는 개발자만 쓰는 설정처럼 보였지만, 반복 설명을 줄이는 메모로 보면 훨씬 이해하기 쉬웠습니다.
AI 프로젝트를 조금만 쓰다 보면 .md라는 파일이 자꾸 보입니다.
README.md
CLAUDE.md
AGENTS.md
SKILL.md
처음 보면 개발자 파일 같아서 살짝 멀어집니다…
저도 예전에는 md 파일이라고 하면 뭔가 코드 프로젝트 안에 있는 설명서 정도로만 생각했어요.
그런데 AI를 프로젝트별로 쓰기 시작하면서 md 파일이 꽤 중요해졌습니다.
특히 지침, 작업 규칙, 반복 설명을 남겨둘 때 유용했어요.
MD는 특별한 AI 파일이 아닙니다
.md는 Markdown 파일입니다.
쉽게 말하면 제목, 목록, 표 같은 구조를 간단한 기호로 표시하는 텍스트 파일이에요.
예를 들어 이런 식입니다.
#은 큰 제목. ##는 중간 제목. -는 목록. | |는 표.
워드 문서처럼 복잡한 서식이 들어간 파일이라기보다, 구조가 있는 메모장에 가깝습니다.
디자이너 기준으로 비유하면 이렇습니다.
txt는 아무 줄 없는 메모지.
md는 제목 스티커와 목록 표시가 붙은 정리된 메모지.
docx는 서식이 많은 문서.
pdf는 인쇄된 최종본.
AI에게는 md 파일이 꽤 읽기 좋습니다.
제목과 목록이 명확해서 어디가 규칙이고, 어디가 예시고, 어디가 설명인지 구분하기 쉽기 때문입니다.
Markdown은 복잡한 디자인 문서가 아니라 구조가 있는 텍스트 파일에 가깝습니다.
README.md는 사람에게 보여주는 안내문입니다
README.md는 보통 프로젝트를 설명하는 안내문입니다.
이 폴더가 무엇인지, 어떻게 쓰는지, 어떤 구조인지 알려주는 문서예요.
디자인 프로젝트라면 이런 내용이 들어갈 수 있습니다.
- 프로젝트 목적
- 폴더 구조
- 주요 파일 설명
- 작업 순서
- 주의할 점
findings에서 확인된 D:\Yugyeong-OS\README.md에는 도구 역할 분담이 정리되어 있었습니다.
GPT: 기획, 글쓰기, 정리, 전략
Claude: 대화, 분석, 아이디어
Claude Code: 실제 실행, 파일 생성, 자동화
이런 문장은 프로젝트를 처음 여는 사람에게도, AI에게도 좋은 안내가 됩니다.
CLAUDE.md는 Claude Code가 읽는 지침입니다
CLAUDE.md는 Claude Code가 프로젝트를 이해할 때 읽는 지침 파일입니다.
Claude 공식 문서 기준으로 CLAUDE.md는 프로젝트, 사용자, 조직 수준의 지속 지침을 담을 수 있고, Claude Code는 세션을 시작할 때 이 파일들을 컨텍스트로 읽습니다.
쉽게 말하면 Claude Code에게 주는 작업방 규칙입니다.
예를 들면:
- 이 프로젝트에서 먼저 읽어야 할 문서
- 수정하면 안 되는 파일
- 작업 전 확인해야 할 규칙
- 반복해서 실수했던 부분
- 테스트나 검수 순서
findings에는 실제 사고 이후 규칙으로 박아둔 사례도 있었습니다.
daily-app 프로젝트의 CLAUDE.md에는 data.db 유실 사고 이후, 해당 파일은 읽기만 하고 수정·삭제하지 말라는 규칙이 들어 있었습니다.
이건 좋은 예시입니다.
실패가 생겼을 때 “다음엔 조심하자”로 끝내지 않고, AI가 읽는 규칙 파일에 날짜와 함께 박아두는 것.
저는 이게 md 파일의 가장 실용적인 쓰임이라고 느꼈습니다.
AGENTS.md는 Codex가 읽는 지침입니다
AGENTS.md는 Codex 같은 코딩 에이전트가 읽는 프로젝트 지침 파일입니다.
OpenAI 공식 문서 기준으로 Codex는 작업 전 AGENTS.md 파일을 읽고, 전역 지침과 프로젝트별 지침을 함께 적용할 수 있습니다. 또 빈 파일은 건너뜁니다.
즉 CLAUDE.md와 AGENTS.md는 내용이 완전히 다른 파일이라기보다, 어떤 도구가 읽는지가 다릅니다.
Claude Code는 CLAUDE.md를 읽고, Codex는 AGENTS.md를 읽습니다.
그래서 같은 규칙을 두 도구 모두에게 알려주고 싶다면 같은 내용을 두 파일명으로 둘 수도 있습니다.
디자이너도 md 파일을 알아두면 좋은 이유
저는 디자이너가 꼭 개발자가 될 필요는 없다고 생각합니다.(당연..)
하지만 AI와 함께 작업하려면, 내 작업 기준을 AI가 읽을 수 있는 형태로 남기는 능력은 점점 중요해질 것 같아요.
md 파일은 그중 가장 가벼운 방식입니다.
특별한 프로그램이 없어도 열 수 있고, 구조가 단순하고, AI가 읽기 좋고, 나중에 버전 관리도 쉽습니다.
저는 앞으로 이런 내용을 md 파일로 남기려고 합니다.
- 프로젝트별 작업 규칙
- 디자인 분석 기준
- 블로그 말투 원칙
- 반복해서 실수한 내용
- AI에게 맡기면 안 되는 판단
- 자주 쓰는 작업 순서
예쁘게 꾸민 문서보다 중요한 건, 다음 작업에서 다시 읽히는 문서입니다.
md 파일은 그 역할을 꽤 잘합니다.
이어 읽기
CLAUDE.md와 AGENTS.md, 프로젝트 지침과 AI 스킬