AI에게 같은 내용을 요청해도 결과가 천차만별인 경험을 해본 적 있는가.
답은 구조에 있다. GitHub, Notion, Stack Overflow — 개발자들이 문서를 잘 쓰는 플랫폼일수록 마크다운 문법이 기본값이다. 우연이 아니다. 사람이 읽기 쉬운 구조는 AI도 읽기 쉽다. LLM의 학습 데이터 상당수가 마크다운으로 작성된 문서이기 때문이다.
이 글에서는 마크다운 문법이 무엇인지, 왜 AI와의 대화에서 중요한지, 그리고 실무에서 바로 쓸 수 있는 핵심 문법 10가지를 정리한다.
마크다운 문법이란 무엇인가 — 경량 마크업 언어부터 이해하자
마크다운은 경량 마크업 언어(Lightweight Markup Language)의 한 종류다.
마크업(Markup)이란 텍스트에 “이건 제목이야”, “이건 굵게 표시해줘” 같은 의미 정보를 붙이는 행위다. 가장 잘 알려진 마크업 언어는 HTML이다. HTML은 기계가 완벽하게 이해하지만, 사람이 직접 쓰기엔 태그가 너무 많고 번거롭다. 그래서 나온 것이 경량 마크업 언어다. 기호 몇 개만으로 같은 구조를 표현한다.
| 의도 | HTML | 마크다운 문법 |
|---|---|---|
| 제목 | <h1>제목</h1> | # 제목 |
| 굵게 | <strong>굵게</strong> | **굵게** |
| 목록 | <ul><li>항목</li></ul> | - 항목 |
마크다운 문법의 핵심 특징은 3가지다.
첫째, 렌더링 없이도 원본 텍스트를 사람이 읽을 수 있다. # 제목이라고 적혀 있으면, 화면에 표시하지 않아도 “제목이구나”를 바로 알 수 있다.
둘째, 최종 결과물이 아닌 변환용 원본이다. .md 파일은 HTML, PDF 등으로 변환되기 위해 존재한다.
셋째, 배우는 데 10분이면 충분하다. HTML 문법은 수백 가지지만 마크다운 핵심 문법은 10개 미만이다.
바이브코딩·프롬프트 엔지니어링에서 마크다운 문법이 중요한 이유
LLM은 토큰 시퀀스를 처리한다. #, **, - 같은 마크다운 문법 기호들은 학습 데이터에 워낙 많이 등장해서 AI가 구조적 패턴으로 인식한다. 즉, 마크다운 문법을 쓰면 AI가 “이건 제목이고, 저건 조건 목록이구나”를 더 정확하게 파악한다.
반대로 평문으로 긴 지시를 쓰면 AI가 중요도를 파악하기 어렵다. 마크다운 문법으로 계층화하면 핵심 지시 → 부가 조건 → 예외의 흐름이 명확해지고, 지시 이행률이 올라간다.
바이브 코딩의 핵심 파일인 CLAUDE.md도 마크다운 문서다. AI가 프로젝트 컨텍스트를 읽을 때 마크다운 구조를 따라 스코프별로 규칙을 구분한다. 잘 작성된 CLAUDE.md와 그렇지 않은 것의 차이는, 결국 마크다운 문법을 얼마나 잘 활용했는지에서 갈린다.
실무에서 바로 쓰는 마크다운 문법 10가지
1. 제목 (Heading) —
# H1 제목
## H2 제목
### H3 제목
# 개수가 계층 깊이를 결정한다. 문서 전체의 뼈대를 잡는 가장 기본적인 마크다운 문법이다. CLAUDE.md 작성 시 ## Role, ## Context, ## Rules 같은 섹션 구분이 여기서 나온다.
2. 굵게 / 기울임 / 취소선
**굵게**
*기울임*
~~취소선~~
모든 것을 강조하면 의미가 없다. 프롬프트에서 진짜 중요한 지시 1~2개에만 **굵게**를 적용하는 것이 효과적이다.
3. 목록 — 순서 없음 / 있음
- 항목 A
- 중첩 항목
1. 첫 번째
2. 두 번째
조건과 제약을 나열할 때 산문보다 목록이 훨씬 낫다. CLAUDE.md의 Rules 섹션은 거의 전부 불릿 목록으로 작성된다. 목록으로 쓰면 AI가 조건을 누락할 확률이 낮아진다.
4. 인라인 코드 / 코드 블록
`인라인 코드`
```python
def hello():
print("Hello")
```
백틱(`) 1개는 인라인, 3개는 블록이다. 코드, 파일명, 명령어를 프롬프트에 포함할 때 코드 블록으로 감싸면 AI가 “이건 실행 대상”임을 명확히 인식한다. 언어명을 붙이면 문법 하이라이팅도 적용된다.
5. 표 (Table)
| 항목 | 설명 | 비고 |
|------|------|------|
| A | 내용 | - |
비교, 조건 정리, 수치 나열에 가장 강력한 마크다운 문법이다. 프롬프트에서 입력/출력 예시를 명확히 제시할 때 표를 쓰면 AI의 이해도가 눈에 띄게 올라간다.
6. 인용 — >
> 이것은 인용문입니다.
참고 문장, AI 응답 예시, 주의 사항을 본문에서 구분할 때 쓴다.
7. 링크 / 이미지
[링크 텍스트](https://example.com)
이미지는 링크 앞에 !만 붙이면 된다.
8. 수평선 — —
---
섹션을 시각적으로 구분할 때 사용한다.
9. 체크박스
- [ ] 아직 안 함
- [x] 완료
CLAUDE.md 작업 목록이나 프로젝트 진행 상황 관리에 쓴다.
10. 이스케이프 — \
\*별표를 텍스트로 출력\*
마크다운 기호를 그대로 문자로 표시하고 싶을 때 앞에 \를 붙인다.
핵심 마크다운 문법 한눈에 정리
| 문법 | 기호 | 주 용도 | CLAUDE.md 활용 |
|---|---|---|---|
| 제목 | # ## ### | 문서 구조 | 섹션 구분 |
| 강조 | ** * ~~ | 텍스트 서식 | 중요 지시 강조 |
| 목록 | - 1. | 나열·순서 | 규칙·조건 열거 |
| 인용 | > | 참고·예시 | 주의사항 구분 |
| 코드 | ` ``` | 코드 표현 | 명령어·파일명 |
| 링크/이미지 | []() ![]() | 참조 연결 | 참고 문서 링크 |
| 수평선 | --- | 섹션 구분 | 파트 분리 |
| 표 | | | | | 비교·정리 | 조건별 규칙 정리 |
| 체크박스 | [ ] [x] | 작업 관리 | 진행 상황 추적 |
| 이스케이프 | \ | 기호 무력화 | — |
이 10가지면 실무 마크다운 문법의 90%는 커버된다. 그중에서도 제목, 목록, 코드 블록, 표 — 이 4가지가 CLAUDE.md 작성과 프롬프트 엔지니어링에서 가장 자주 쓰인다.
핵심 요약
- 마크다운 문법은 AI에게 텍스트의 “의도와 구조”를 전달하는 시각적 신호다.
- 바이브코딩과 프롬프트 엔지니어링에서 마크다운 문법을 잘 쓸수록 AI의 지시 이행률이 올라간다.
- 핵심은 4가지다. 제목으로 구조를 잡고, 목록으로 조건을 나열하고, 코드 블록으로 코드를 감싸고, 표로 규칙을 정리하면 — AI는 훨씬 정확하게 의도를 읽는다.
- 마크다운 문법 자체보다 “왜 써야 하는가”를 이해하는 것이 먼저다. 구조화된 글은 사람도, AI도 더 잘 읽는다.
다음 포스팅에서는 이 마크다운 지식을 바탕으로 실전 CLAUDE.md 템플릿을 직접 작성하는 방법을 다룬다.
[링크 제안]
마크다운 문법을 익혔다면, 다음 단계는 실제 바이브코딩 프로젝트에 적용하는 것이다. 30일 실전 후기에서 마크다운이 어떻게 쓰이는지 확인해보자.
마크다운 구조화 능력은 프롬프트 엔지니어링의 핵심 기술이다. 초기 세팅 원칙을 함께 읽으면 시너지가 난다.
자비스는 어떻게 만들어졌을까 — Agentic AI의 시작
