Markdown (마크다운) — 에이전트 개발의 공용어
안티그래비티(Antigravity)·클로드 코드(Claude Code)·커서(Cursor) 등 거의 모든 AI 에이전트의 설정·규칙·스킬 파일은 마크다운(.md)으로 작성됩니다. 마크다운 문법을 알면 에이전트가 의도를 더 정확히 이해하고, 가독성 높은 산출물을 자동으로 만들 수 있습니다.
1. 왜 에이전트 개발에 마크다운이 필요한가? #
현재 보편적으로 쓰이는 AI 코딩 에이전트들이 설정 파일·규칙·스킬을 모두 마크다운으로 정의합니다. 이는 우연이 아니라, 마크다운이 사람과 LLM 모두에게 가장 적합한 형식이기 때문입니다.
1.1 모든 에이전트 설정 파일이 마크다운입니다
| 에이전트 / 도구 | 대표 설정 파일 | 역할 |
|---|---|---|
| 안티그래비티(Antigravity) | .agents/rules/*.md, ~/.gemini/GEMINI.md |
에이전트 행동 규칙·컨벤션 |
| 안티그래비티 스킬(Antigravity Skills) | .agents/skills/<name>/SKILL.md |
도메인 지식·다단계 절차 |
| 클로드 코드(Claude Code) | CLAUDE.md, ~/.claude/CLAUDE.md |
프로젝트·전역 컨텍스트 주입 |
| 커서(Cursor) | .cursor/rules/*.mdc |
코드 스타일·컨벤션 정의 |
| 깃허브 코파일럿(GitHub Copilot) | .github/copilot-instructions.md |
저장소 단위 가이드라인 |
| 공식 문서·README | README.md, docs/*.md |
프로젝트 설명·온보딩 자료 |
1.2 LLM이 마크다운을 잘 이해합니다
LLM의 학습 데이터에는 GitHub README, Stack Overflow, 공식 문서가 압도적으로 많이 포함됩니다. 이들은 거의 모두 마크다운으로 작성되어 있어, 모델은 마크다운 구조를 자연스럽게 인식합니다.
- 제목 계층(
#,##) → 모델은 이를 "문서 섹션의 중요도"로 해석합니다. 핵심 규칙은##레벨로, 부가 설명은###이하로 두면 우선순위가 명확해집니다. - 목록(
-,1.) → "병렬적인 항목"으로 인식되어, 빠뜨리지 않고 순회할 가능성이 높아집니다. - 코드 블록(
```) → 모델이 "이 부분은 그대로 출력해야 하는 코드"라고 명확히 구분합니다. - 표 → 비교·매핑 정보를 한눈에 파악하게 도와, 잘못된 매칭 확률을 낮춥니다.
1.3 마크다운이 가져다주는 실질적 이점
- 버전 관리 친화적 — 일반 텍스트라 git diff가 깔끔하게 나옵니다. 워드 문서나 Notion은 변경 이력 추적이 까다롭습니다.
- 도구 독립적 — VS Code, Vim, Obsidian, GitHub 웹 어디서든 그대로 읽고 편집됩니다.
- HTML로 즉시 변환 — 같은 파일이 README, 블로그, 문서 사이트로 다목적 활용됩니다.
- 학습 곡선이 매우 짧음 — 핵심 문법 8가지만 알면 90% 사용 가능합니다.
2. 기본 문법 — 8가지만 알면 충분 #
실무에서 가장 많이 쓰는 핵심 문법입니다. 각 항목마다 마크다운 원본 → 렌더링 결과 → 에이전트 파일에서의 용도 순으로 설명합니다.
2.1 제목 (Heading)
#의 개수가 제목 레벨을 나타냅니다 (1~6단계).
# 가장 큰 제목 (h1)
## 섹션 제목 (h2)
### 하위 섹션 (h3)
#### 더 깊은 단계 (h4)
GEMINI.md의 ## 헤더는 모델이 "주요 규칙 카테고리"로 인식합니다. 한 파일에 #은 1개만, ##로 큰 섹션을 나누고 ### 이하로 세부 항목을 두는 것을 권장합니다.
2.2 강조 (Bold / Italic)
**굵게** — 핵심 키워드 강조 (가장 많이 사용)
*기울임* — 부가 설명, 인용 출처
***굵은 기울임*** — 두 가지 동시 적용
~~취소선~~ — 삭제·금지된 항목 표시
**굵게**로 표시하면 모델이 우선순위를 더 잘 인식합니다. *기울임*은 한국어에서 시각적 효과가 약하므로 굵게를 우선 사용합니다.
2.3 목록 (List)
- 첫 번째 항목
- 두 번째 항목
- 들여쓰기 2칸으로 하위 항목
- 또 다른 하위 항목
- 세 번째 항목
1. 의존성 설치
2. 환경 변수 설정
3. 서버 실행
1. 개발 모드: `npm run dev`
2. 프로덕션 모드: `npm start`
- [x] 완료한 작업
- [ ] 진행 중인 작업
- [ ] 아직 시작 안 한 작업
1.)으로, 병렬적인 규칙·금지 사항은 순서 없는 목록(-)으로 작성하세요. 에이전트는 두 형식의 의미를 다르게 해석합니다.
2.4 코드 블록 & 인라인 코드
변수명은 `snake_case`로 작성하고, 함수는 `verb_noun()` 형식을 따릅니다.
```python
import pandas as pd
def load_csv(path: str) -> pd.DataFrame:
return pd.read_csv(path, encoding='utf-8')
```
```python)은 매우 중요합니다. 에이전트는 이를 보고 "그대로 실행하거나 그대로 따라야 할 코드"로 인식합니다. 인라인 코드(`...`)는 파일 경로·명령어·변수명 등 짧은 식별자에 사용하세요.
2.5 링크 & 이미지
[링크 텍스트](https://example.com)
[Antigravity 공식 문서](https://antigravity.google/docs)
[같은 저장소 다른 파일](./CONTRIBUTING.md)
[같은 파일 다른 섹션](#section-basics)


./docs/style.md)를 따라가 추가 컨텍스트를 자동으로 읽습니다. Rules·Skills 파일에서 자주 쓰이는 보조 문서를 링크로 연결해두면 컨텍스트 효율이 크게 개선됩니다.
2.6 표 (Table)
| 환경 | 명령어 | 비고 |
|------|--------|------|
| 개발 | `npm run dev` | 핫 리로드 활성화 |
| 빌드 | `npm run build` | dist/ 폴더에 출력 |
| 배포 | `npm run deploy` | main 브랜치만 가능 |
두 번째 줄의 :------: 정렬 마크로 정렬을 지정할 수 있습니다 (:-- 왼쪽, :-: 가운데, --: 오른쪽).
2.7 인용 (Blockquote)
> 중요: 이 함수는 비동기로 실행되므로 await 키워드가 필요합니다.
> **참고:** 여러 줄 인용도 가능합니다.
> 두 번째 줄도 같은 인용 블록 안에 들어갑니다.
2.8 수평선 & 줄바꿈
섹션 1 내용
---
섹션 2 내용 (위 수평선으로 구분)
문장 끝에 공백 두 칸을 넣으면
같은 단락 안에서 줄바꿈됩니다.
3. 에이전트 파일에서의 실전 활용 #
이론보다 실제 파일을 보는 것이 가장 빠릅니다. 아래는 에이전트 설정 파일에서 자주 쓰이는 마크다운 패턴 모음입니다.
3.1 Rules 파일 (.agents/rules/data-conventions.md)
# description: CSV·Excel·DB 데이터를 다룰 때 적용되는 한국어 데이터 분석 컨벤션
# globs: **/*.csv, **/*.xlsx, **/*.ipynb
## 인코딩 규칙
- CSV 읽기 시 **반드시 `encoding='utf-8'`을 명시**합니다.
- 한국어 파일명은 `cp949` 폴백을 시도하지 않고 사용자에게 변환을 요청합니다.
## 결측치 처리
| 데이터 유형 | 처리 방법 |
|------------|----------|
| 수치형 | 중앙값으로 대체 |
| 범주형 | 최빈값으로 대체 |
| 시계열 | 직전 값으로 forward fill |
## 시각화
- 한글 폰트 문제로 **seaborn 스타일은 사용하지 않습니다**.
- matplotlib + `koreanize_matplotlib`을 import 순서에 맞춰 사용합니다.
```python
import koreanize_matplotlib # 반드시 먼저
import matplotlib.pyplot as plt
```
이 파일에서 마크다운 요소가 어떻게 동작하는지 살펴보세요.
- 맨 위 주석 헤더(
# description:,# globs:) — Antigravity가 메타데이터로 인식 ##섹션 제목 — 인코딩·결측치·시각화 등 주제별 그룹화- 표 — "데이터 유형별 처리 방법" 매핑이 한눈에 보임
- 코드 블록 — 에이전트가 그대로 따라야 할 import 순서를 명확히 지정
3.2 Skills 파일 (.agents/skills/data-cleanup/SKILL.md)
# Data Cleanup Skill
description: CSV·Excel 데이터를 받으면 결측치 리포트 → 이상치 제거 → 정제본 저장까지 자동화합니다.
## 트리거 조건
다음 키워드 중 하나가 사용자 요청에 포함되면 활성화하세요.
- "데이터 정제", "데이터 클리닝"
- "결측치 처리", "이상치 제거"
- "전처리해줘"
## 실행 단계
1. **데이터 로드** — 파일 확장자에 맞는 라이브러리 선택
2. **품질 리포트 생성** — `df.info()`, `df.describe()`, 결측치 비율
3. **이상치 탐지** — IQR 1.5배 기준
4. **정제본 저장** — `cleaned_{원본파일명}.csv`
## 보고 형식
리포트는 다음 마크다운 형식으로 작성합니다.
```markdown
## 데이터 품질 리포트
- 총 행: {n_rows}
- 총 열: {n_cols}
- 결측치 비율: {missing_pct}%
```
3.3 GEMINI.md (전역 컨텍스트)
# 사용자 정보
- 역할: 데이터 분석가
- 주 사용 언어: Python (pandas, matplotlib), R, SQL
- 한국어로 응답하되, **코드 주석·변수명은 영어**로 유지
## 응답 스타일
- 결론 먼저, 근거는 뒤에
- 코드를 제시하면 **반드시 실행 결과 예시**를 함께 보여줄 것
- 추측이 필요한 부분은 명확히 표기 ("추정:")
## 자주 쓰는 도구
| 작업 | 선호 도구 |
|------|----------|
| 데이터 탐색 | pandas + ydata-profiling |
| 시각화 | matplotlib + koreanize_matplotlib |
| 통계 검정 | scipy.stats |
##) → 짧은 설명 → 목록 또는 표"의 반복 구조입니다. 긴 산문보다 구조화된 리스트·표가 모델에게 훨씬 잘 전달됩니다.
4. 자주 하는 실수와 해결 #
4.1 들여쓰기로 인한 목록 깨짐
- 상위 항목
- 1칸 들여쓰기 (인식 안 됨)
- 3칸 들여쓰기 (애매함)
- 상위 항목
- 2칸 들여쓰기
- 또 다른 하위 항목
- 4칸 들여쓰기 (더 깊은 단계)
4.2 코드 블록 안에서 백틱 사용
코드 안에 백틱을 포함해야 한다면 4개 이상의 백틱으로 바깥을 감싸세요.
````markdown
인라인 코드 예시: `print("hello")`
```python
print("hello")
```
````
4.3 표 정렬과 셀 안 줄바꿈
마크다운 표는 한 셀에 여러 줄을 넣을 수 없습니다. 줄바꿈이 필요하면 <br>을 직접 쓰거나, 표 대신 일반 목록으로 변환하세요.
4.4 한국어 헤더 앵커 깨짐
일부 도구는 한국어 제목으로 자동 생성된 앵커 링크를 깨뜨릴 수 있습니다. 중요한 섹션은 명시적 ID를 부여하세요.
## <a id="rules-create"></a>Rules 만들기
[이 섹션으로 이동](#rules-create)
4.5 특수 문자 이스케이프
마크다운 문법으로 해석되는 문자(* _ # [ ] ( ))를 그대로 출력하려면 백슬래시(\)로 이스케이프합니다.
가격: \$100 (이스케이프 없으면 LaTeX 수식으로 해석될 수 있음)
별표 강조 없이 \*표시\* 그대로 출력
4.6 너무 깊은 헤더 계층
###### 같은 6단계 헤더를 쓸 정도로 계층이 깊어지면 글의 구조가 잘못된 것입니다. 4단계(####) 이상은 새 파일로 분리하거나 목록으로 풀어쓰세요.
5. 한 페이지 치트시트 #
북마크해두고 필요할 때마다 참고하세요.
| 기능 | 문법 | 예시 |
|---|---|---|
| 제목 | # ## ### #### | ## 섹션 제목 |
| 굵게 | **텍스트** | **중요한 규칙** |
| 기울임 | *텍스트* | *부가 설명* |
| 취소선 | ~~텍스트~~ | ~~삭제된 항목~~ |
| 인라인 코드 | `코드` | `pd.read_csv()` |
| 코드 블록 | ```언어 | ```python |
| 순서 없는 목록 | - 항목 | - 첫 번째 |
| 순서 있는 목록 | 1. 항목 | 1. 첫 단계 |
| 체크리스트 | - [x] / - [ ] | - [x] 완료 |
| 링크 | [텍스트](URL) | [공식 문서](https://...) |
| 이미지 |  |  |
| 인용 | > 텍스트 | > 중요한 메모 |
| 수평선 | --- | --- |
| 표 | | 헤더 | | 본문 2.6 참조 |
| 이스케이프 | \문자 | \* 별표 그대로 |
- Rules (규칙) — 첫
.md규칙 파일을 만들어 봅니다 - Skills (스킬) —
SKILL.md로 다단계 절차를 캡슐화합니다 - Workflows (워크플로우) — 슬래시 명령으로 호출하는 템플릿을 만듭니다