AI 시대에 마크다운이 중요한 이유: md 파일 뜻과 역할
마크다운은 기호 몇 개로 제목과 목록 같은 문서 구조를 표시하는 작성 방식입니다. AI 코딩 도구의 규칙 파일과 스킬 파일, 구조를 나눈 프롬프트에 두루 쓰이는 이유와 초보자가 바로 쓸 문법을 설명합니다.
목차
세 줄로 먼저 읽기
이번 방문에서 한 편은 바로 볼 수 있습니다.
마크다운은 이미 쓰고 있던 작성 방식입니다
노션(Notion)에서 #과 스페이스로 제목을 만들거나 채팅에서 별표로 강조하는 방식을 보았을 것입니다. 다만 도구마다 문법이 같다고 생각하면 안 됩니다. 일반 마크다운에서는 **굵게**가 굵은 글씨이고 *기울임*은 기울임입니다. Slack의 메시지 서식 등은 자체 규칙을 쓰므로 다른 편집기에 그대로 옮기면 모양이 달라질 수 있습니다. 마크다운은 기호 몇 개로 제목, 목록, 강조 같은 문서 구조를 표시하는 작성 방식입니다. 개발자만 쓰는 언어가 아니라 이미 많은 도구에서 매일 쓰는 방식입니다.
예전에는 주로 README 파일(프로그램 설명서)이나 블로그 글을 쓰는 데 쓰였습니다. 요즘은 쓰임이 하나 더 늘었습니다. AI 코딩 도구가 읽는 규칙 파일과 작업 절차 파일이 대부분 .md 확장자의 마크다운 파일입니다. 사람이 적어 둔 규칙을 AI가 읽고 작업에 반영하는 방식이라, 마크다운을 알면 AI 도구에 일하는 방법을 알려 줄 수 있습니다.
AI 도구가 읽는 md 파일
AI 에이전트는 사람이 맡긴 작업을 여러 단계로 나눠 스스로 진행하는 AI 도구입니다. 클로드 코드(Claude Code), 코덱스(Codex), 커서(Cursor) 같은 도구가 여기에 속합니다. 이런 도구는 정해진 위치와 이름의 지침 파일을 읽는 기능을 제공합니다. 모든 md 파일을 자동으로 읽는 것은 아니며 도구별 설정과 읽는 시점을 확인해야 합니다.
CLAUDE.md와 AGENTS.md: 프로젝트 규칙 파일
클로드 코드는 시작 위치와 상위 경로의 프로젝트용 CLAUDE.md 등을 읽고 하위 폴더의 지침은 해당 폴더의 파일을 읽을 때 추가할 수 있습니다. 다음은 개발자가 쓰는 지침 예입니다. TypeScript는 프로그래밍 언어, camelCase는 sendReport처럼 단어를 이어 쓰는 이름 방식, JSDoc은 코드 설명 주석의 형식입니다. 개발을 하지 않는다면 아래 코드 규칙을 외우거나 자신의 파일에 넣을 필요는 없습니다.
## 코드 스타일
- TypeScript를 쓴다
- 함수 이름은 camelCase로 쓴다
- 모든 함수에 JSDoc 주석을 단다
## 하지 않을 것
- any 타입을 쓰지 않는다
- console.log 대신 logger를 쓴다매번 "TypeScript로 써 줘, camelCase로 해 줘"라고 반복하지 않아도 됩니다. 다만 규칙 파일은 AI가 참고하는 지침이지 반드시 지켜지는 설정은 아니어서, 결과물은 따로 확인해야 합니다.
코덱스 같은 여러 도구는 같은 역할의 파일을 AGENTS.md라는 공통 이름으로 읽습니다. Codex 지침 파일 안내 클로드 코드도 2026년 9월 공개한 v2.1.277부터 조건에 따라 AGENTS.md를 읽기 시작했습니다. 읽는 조건은 클로드 코드 AGENTS.md 지원 정리에 따로 적어 두었습니다.
SKILL.md: 반복 작업 절차 파일
스킬(Skill)은 반복하는 작업의 절차를 SKILL.md 파일에 적어 두고, 필요할 때 AI가 불러 쓰게 하는 기능입니다. 지침 파일은 작업의 공통 기준이고 스킬은 특정 작업의 절차를 담는다는 차이가 있습니다. 앤트로픽이 만든 형식이고, 여러 도구가 같은 파일을 읽을 수 있도록 공개 표준(agentskills.io)으로도 정리돼 있습니다.
예를 들어 마케팅팀의 주간 뉴스레터 스킬 본문 일부는 아래와 같습니다. 완성된 설치용 SKILL.md 파일은 아닙니다.
## 작업 순서
### 1단계: 이번 주 소식 모으기
- 지정한 업계 뉴스 사이트 5곳에서 주요 기사를 찾는다
- 자사 블로그의 새 글 목록을 확인한다
### 2단계: 고르고 요약하기
- 마케터에게 쓸모 있는 기사 5개를 고른다
- 기사마다 3줄로 요약하고 원문 링크를 붙인다
### 3단계: 초안 쓰기
- 인사말, 이번 주 핵심 소식, 기사 요약 순서로 쓴다
- 완성본이 아니라 초안으로 담당자에게 넘긴다이 절차를 실제 스킬로 등록하려면 표준이 요구하는 name과 description 등의 머리말 정보와 도구가 지원하는 저장 위치를 맞춰야 합니다. 머리말 정보는 문서의 이름과 용도를 알려 주는 메타데이터입니다. AI가 해당 스킬을 선택해 읽었는지도 확인합니다. 스킬을 읽은 뒤에도 기사 출처와 요약을 검토하고, 초안 작성과 실제 발송 권한을 구분합니다.
코딩을 몰라도 쓸 수 있는 이유
지침의 본문은 #으로 제목을 쓰고 -로 목록을 만드는 정도로도 시작할 수 있습니다. 실제 적용에는 앞에서 설명한 파일 위치와 메타데이터 등 도구별 조건을 함께 맞춥니다. 메모장에서 열어 사람이 그대로 읽고 고칠 수 있고, AI는 제목과 목록으로 어디까지가 한 규칙인지 알아봅니다. 사람과 AI가 같은 파일을 함께 읽고 고칠 수 있다는 점이 규칙 파일에 마크다운이 쓰이는 가장 실용적인 이유로 보입니다.
| 역할 | md 파일로 적어 둘 만한 것 |
|---|---|
| 마케터 | 광고 문구 규칙: 대상, 채널, 쓰지 않을 표현 |
| 기획자 | 회의록 정리 절차: 요약 형식, 할 일 뽑는 기준 |
| 콘텐츠 담당자 | 뉴스레터 초안 절차: 소식 모으기, 요약, 초안 형식 |
| 데이터 분석가 | 리포트 작성 절차: 데이터 출처, 표 형식, 해석할 때 주의점 |
프롬프트를 나누면 조건을 확인하기 쉽습니다
긴 요청을 줄글로 쓰면 무엇이 요청이고 무엇이 조건인지 AI가 구분하기 어려울 때가 있습니다.
줄글로 요청한 경우:
우리 회사 SNS 마케팅 전략을 짜줘. 대상은 20대 여성이고 예산은 월 500만원이야. 인스타그램이랑 틱톡 위주로 해줘. KPI도 넣어줘.마크다운으로 구역을 나눈 경우:
## 요청
SNS 마케팅 전략 수립
## 조건
- 대상: 20대 여성
- 월 예산: 500만원
- 채널: 인스타그램, 틱톡
## 결과 형식
1. 채널별 예산 배분 (표로)
2. 월간 콘텐츠 일정
3. KPI(핵심성과지표) 목표: 클릭률, 전환율, 팔로워 증가율두 번째 예시에는 결과 형식 등 추가 조건도 들어 있으므로 두 예시가 문법만 바꾼 성능 비교는 아닙니다. KPI는 목표의 진행을 확인하는 핵심 지표이며, 현재 실적이 없는 상태에서 AI가 만든 목표값은 근거 있는 목표가 아니라 가정일 수 있습니다. 실제 계획에서는 기준 실적과 목표값의 근거를 함께 확인합니다.
두 번째 요청은 요청, 조건, 결과 형식이 제목으로 나뉘어 있어 조건 하나가 빠졌는지 사람도 쉽게 확인할 수 있습니다. 결과 형식을 번호 목록으로 적으면 답도 그 순서로 오는 경우가 많습니다.
AI 회사들의 공식 가이드도 비슷한 방법을 권합니다. OpenAI는 제목과 목록 등 마크다운 또는 XML 태그로 지시와 자료의 경계를 표시하는 방법을 안내하고, 앤트로픽은 긴 프롬프트를 XML 태그(<조건>처럼 꺾쇠 괄호로 감싼 이름표)로 나누라고 권합니다. 형식은 달라도 구역을 나눠 요청과 자료가 섞이지 않게 하라는 점은 같습니다. 짧은 질문이라면 줄글로도 충분합니다.
검색엔진과 마크다운의 관계
블로그를 마크다운으로 쓰면 ## 소제목이 웹페이지의 <h2> 제목 태그로, 가 <img alt="설명">으로 바뀝니다. 웹용 변환 프로그램이 제목과 목록, 이미지 설명을 HTML 요소로 만듭니다.
| 마크다운 | 바뀌는 HTML | 뜻 |
|---|---|---|
## 소제목 | <h2>소제목</h2> | 구역의 제목 |
- 항목 | <ul><li>항목</li></ul> | 목록 |
[텍스트](URL) | <a href="URL">텍스트</a> | 다른 페이지로 가는 링크 |
 | <img alt="설명" src="이미지"> | 이미지와 그 설명(alt 텍스트) |
다만 이것이 검색 순위를 바로 올린다는 뜻은 아닙니다. 구글의 SEO 기본 가이드는 제목 태그의 순서가 틀려도 구글 검색 입장에서는 문제가 되지 않고, 이상적인 제목 개수도 없다고 설명합니다. 제목 순서를 지키면 화면 낭독기를 쓰는 사람이 읽기 좋아지는 것이 확실한 이점입니다.
이미지 설명도 마찬가지입니다. 구글은 alt 텍스트를 이미지 내용을 이해하는 데 쓰지만, 마크다운이 alt를 자동으로 채워 주지는 않습니다. 처럼 괄호를 비워도 이미지는 들어가기 때문에, 설명은 직접 적어야 합니다.
AI 활용에 필요한 마크다운 문법 6가지
아래는 프롬프트와 규칙 파일을 작성할 때 자주 쓰는 여섯 가지입니다. 파일 이름과 위치 등 도구가 요구하는 조건은 별도로 따라야 합니다.
| 문법 | 쓰는 법 | 결과 |
|---|---|---|
| 제목 | ## 제목 | 제목 (# 개수로 단계 조절) |
| 굵게 | **중요** | 중요 |
| 목록 | - 항목 | 글머리 기호 목록 |
| 번호 목록 | 1. 항목 | 순서 있는 목록 |
| 코드 | `코드` | 코드 표시 |
| 표 | 아래의 머리글, 구분선과 자료 행을 함께 작성 | 지원하는 편집기에서 표 |
표는 아래처럼 구분선까지 있어야 합니다. 표는 CommonMark 기본 문법에 없는 확장 문법이므로 편집기의 지원 여부를 확인합니다.
| 항목 | 값 |
| --- | --- |
| 예산 | 500만 원 |가상 일정 메모로 요청을 만듭니다
메모장에 아래 내용을 복사해 요청-연습.md로 저장합니다. 파일 저장이 처음이면 마크다운 파일 만들기의 첫 연습부터 진행합니다. 기존 CLAUDE.md나 AGENTS.md를 바꾸는 연습은 아닙니다.
## 요청
아래 가상 자료에서 할 일만 표로 정리합니다.
## 조건
- 자료에 없는 담당자나 날짜는 미정으로 적습니다.
- 한 행에 한 가지 할 일만 적습니다.
- 메일이나 메시지는 보내지 않고 정리한 표만 답합니다.
## 자료
안내문 초안은 민수가 10월 8일까지 작성합니다.
표지 이미지는 수정하기로 했지만 담당자와 마감일은 정하지 않았습니다.
## 결과 형식
할 일, 담당자, 마감일의 세 열을 가진 마크다운 표로 답합니다.이미 쓰는 AI 채팅의 새 대화에 파일 내용 전체를 붙여 넣고 요청합니다. 파일을 컴퓨터에 저장한 것만으로 채팅 AI가 읽는 것은 아닙니다. 추가 계정이나 유료 도구가 없어도 메모장에서 예상 표를 직접 작성하는 연습은 가능합니다.
정리된 표는 다음 조건을 만족해야 합니다.
| 할 일 | 담당자 | 마감일 |
|---|---|---|
| 안내문 초안 작성 | 민수 | 10월 8일 |
| 표지 이미지 수정 | 미정 | 미정 |
행의 표현이 조금 달라도 자료와 의미가 같으면 됩니다. 표지 담당자가 민수이거나 마감일이 10월 8일로 채워졌다면 AI가 자료에 없는 내용을 보탠 것입니다. 아래처럼 수정 요청을 적고 다시 확인합니다.
표지 이미지의 담당자와 마감일은 원문에 없습니다.
그 두 칸을 미정으로 고치고 다른 칸은 원문과 대조해 주세요.혼자 반복할 때는 원본 자료의 첫 날짜만 10월 11일로 바꾸고 같은 요청을 새 대화에서 다시 실행합니다. 안내문 마감일만 10월 11일이 되고 표지의 두 칸은 미정이어야 합니다. 이전 답을 그대로 복사했다면 날짜가 바뀌었는지, 없는 정보가 추가됐는지 확인합니다.
제목과 목록을 넣었다고 결과가 항상 맞는 것은 아닙니다. 구조를 나누는 목적은 조건을 명확히 전달하고 사람이 원문과 결과를 대조하기 쉽게 만드는 데 있습니다. 한 번의 좋은 답만으로 줄글보다 언제나 우수하다고 판단하지 않습니다.
Sources:
- Manage Claude's memory (클로드 코드 공식 문서)
- Agent Skills 파일 형식
- Prompting best practices (앤트로픽 공식 문서)
- Prompt engineering (OpenAI 공식 문서)
- SEO Starter Guide (구글 검색 센터)
2026년 10월 3일에 공식 문서의 지침 파일과 스킬 형식 및 프롬프트 구분 방법을 확인했습니다.
자주 묻는 질문
md 파일이 뭔가요?
마크다운으로 쓴 문서 파일입니다. ##으로 제목을 만들고 -로 목록을 만드는 것처럼, 기호 몇 개로 문서의 구조를 표시합니다. 확장자가 .md이고 메모장 같은 편집기로 열어 그대로 읽고 고칠 수 있습니다.
md 파일은 무엇으로 여나요?
일반 텍스트라서 메모장, VS Code, 옵시디언 같은 편집기 어디서나 열립니다. VS Code나 옵시디언처럼 미리 보기를 지원하는 편집기에서는 기호가 적용된 화면을 옆에 띄워 확인할 수 있습니다. 별도 프로그램을 사지 않아도 됩니다.
AI에게 질문할 때 마크다운을 쓰면 정말 다른가요?
조건이 많은 요청에서는 제목과 목록이 요청과 자료를 구분하고 누락을 확인하는 데 도움이 됩니다. 다만 정확성이 자동으로 높아지는 보장은 아닙니다. 같은 자료와 기준으로 결과를 대조하며 짧은 질문은 줄글로도 충분합니다.
마크다운 문법을 다 외워야 하나요?
처음에는 제목과 목록부터 써도 됩니다. 굵게와 코드 및 표는 필요한 순간에 예시를 복사해 쓰고 결과를 확인합니다. 스킬의 머리말 정보처럼 도구가 요구하는 형식은 마크다운 기호와 별도로 익힙니다.
제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
AI 에이전트 도구인 Claude Code에서 AI의 행동 규칙을 정의하는 파일의 이름은 무엇일까요?
예제나 확인 질문을 직접 시도한 뒤 완료 표시해요. 더 연습할 내용이 남으면 표시하지 않고 다음 글을 읽어도 됩니다. 완료 버튼은 이해도를 채점하지 않으며 잘못 표시하면 취소할 수 있어요.
이 글이 도움이 되었나요?
AI에게 맡기기 전에 알아야 할 터미널, Git, 배포 기초입니다
코스 전체 보기 →
새 글과 AI 소식을 메일로 받아 보세요
AI가 바꾸는 일과 도구, 측정 실무 이야기를 매주 한 번 보내 드려요.