본문으로 건너뛰기
테마
폰트
크기
A A

Markdown (마크다운) — 에이전트 개발의 공용어

안티그래비티(Antigravity)·클로드 코드(Claude Code)·커서(Cursor) 등 거의 모든 AI 에이전트의 설정·규칙·스킬 파일은 마크다운(.md)으로 작성됩니다. 마크다운 문법을 알면 에이전트가 의도를 더 정확히 이해하고, 가독성 높은 산출물을 자동으로 만들 수 있습니다.

이 페이지의 목적: 마크다운을 처음 접하는 분도 30분 안에 에이전트 설정 파일을 직접 작성·수정할 수 있도록 꼭 필요한 문법만 추렸습니다. 일반 마크다운 입문서와 달리, "에이전트가 잘 읽는 글" 관점에서 설명합니다.

1. 왜 에이전트 개발에 마크다운이 필요한가? #

현재 보편적으로 쓰이는 AI 코딩 에이전트들이 설정 파일·규칙·스킬을 모두 마크다운으로 정의합니다. 이는 우연이 아니라, 마크다운이 사람과 LLM 모두에게 가장 적합한 형식이기 때문입니다.

1.1 모든 에이전트 설정 파일이 마크다운입니다

주요 AI 에이전트의 마크다운 설정 파일
에이전트 / 도구 대표 설정 파일 역할
안티그래비티(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.) → "병렬적인 항목"으로 인식되어, 빠뜨리지 않고 순회할 가능성이 높아집니다.
  • 코드 블록(```) → 모델이 "이 부분은 그대로 출력해야 하는 코드"라고 명확히 구분합니다.
  • → 비교·매핑 정보를 한눈에 파악하게 도와, 잘못된 매칭 확률을 낮춥니다.
한 줄 비유
마크다운은 사람과 LLM이 동시에 읽는 "이중 언어"입니다. 같은 파일이 사람 눈에는 깔끔한 문서로, 모델 눈에는 구조화된 지시문으로 보입니다.

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)

순서 없는 목록 (Unordered)
- 첫 번째 항목
- 두 번째 항목
  - 들여쓰기 2칸으로 하위 항목
  - 또 다른 하위 항목
- 세 번째 항목
순서 있는 목록 (Ordered)
1. 의존성 설치
2. 환경 변수 설정
3. 서버 실행
   1. 개발 모드: `npm run dev`
   2. 프로덕션 모드: `npm start`
체크리스트 (GitHub Flavored)
- [x] 완료한 작업
- [ ] 진행 중인 작업
- [ ] 아직 시작 안 한 작업
에이전트 파일 활용: 여러 단계로 이뤄진 절차는 순서 있는 목록(1.)으로, 병렬적인 규칙·금지 사항은 순서 없는 목록(-)으로 작성하세요. 에이전트는 두 형식의 의미를 다르게 해석합니다.

2.4 코드 블록 & 인라인 코드

인라인 코드 (한 줄 안)
변수명은 `snake_case`로 작성하고, 함수는 `verb_noun()` 형식을 따릅니다.
언어 지정 코드 블록 (3개의 백틱)
```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)
이미지
![대체 텍스트](경로/또는/URL.png)
![아키텍처 다이어그램](./docs/architecture.png)
에이전트 파일 활용: 에이전트는 같은 저장소 안의 상대 경로 링크(./docs/style.md)를 따라가 추가 컨텍스트를 자동으로 읽습니다. Rules·Skills 파일에서 자주 쓰이는 보조 문서를 링크로 연결해두면 컨텍스트 효율이 크게 개선됩니다.

2.6 표 (Table)

마크다운 원본
| 환경 | 명령어 | 비고 |
|------|--------|------|
| 개발 | `npm run dev` | 핫 리로드 활성화 |
| 빌드 | `npm run build` | dist/ 폴더에 출력 |
| 배포 | `npm run deploy` | main 브랜치만 가능 |

두 번째 줄의 :------: 정렬 마크로 정렬을 지정할 수 있습니다 (:-- 왼쪽, :-: 가운데, --: 오른쪽).

에이전트 파일 활용: 비교·매핑 정보(예: 모드별 사용 시점)는 표로 정리하면 에이전트가 항목을 잘못 매칭할 확률이 크게 줄어듭니다. 단, 행이 8개 이상이면 가독성이 떨어지니 분할을 고려하세요.

2.7 인용 (Blockquote)

마크다운 원본
> 중요: 이 함수는 비동기로 실행되므로 await 키워드가 필요합니다.

> **참고:** 여러 줄 인용도 가능합니다.
> 두 번째 줄도 같은 인용 블록 안에 들어갑니다.
에이전트 파일 활용: 경고·중요 사항을 인용 블록으로 감싸면 모델이 일반 본문보다 강조해서 인식합니다. 단, 남발하면 강조 효과가 사라집니다.

2.8 수평선 & 줄바꿈

마크다운 원본
섹션 1 내용

---

섹션 2 내용 (위 수평선으로 구분)

문장 끝에 공백 두 칸을 넣으면
같은 단락 안에서 줄바꿈됩니다.

3. 에이전트 파일에서의 실전 활용 #

이론보다 실제 파일을 보는 것이 가장 빠릅니다. 아래는 에이전트 설정 파일에서 자주 쓰이는 마크다운 패턴 모음입니다.

3.1 Rules 파일 (.agents/rules/data-conventions.md)

data-conventions.md — Workspace Rules 예시
# 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)

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 (전역 컨텍스트)

~/.gemini/GEMINI.md (사용자 전역) 예시
# 사용자 정보

- 역할: 데이터 분석가
- 주 사용 언어: Python (pandas, matplotlib), R, SQL
- 한국어로 응답하되, **코드 주석·변수명은 영어**로 유지

## 응답 스타일

- 결론 먼저, 근거는 뒤에
- 코드를 제시하면 **반드시 실행 결과 예시**를 함께 보여줄 것
- 추측이 필요한 부분은 명확히 표기 ("추정:")

## 자주 쓰는 도구

| 작업 | 선호 도구 |
|------|----------|
| 데이터 탐색 | pandas + ydata-profiling |
| 시각화 | matplotlib + koreanize_matplotlib |
| 통계 검정 | scipy.stats |
핵심 패턴: 에이전트 설정 파일은 대부분 "제목(##) → 짧은 설명 → 목록 또는 표"의 반복 구조입니다. 긴 산문보다 구조화된 리스트·표가 모델에게 훨씬 잘 전달됩니다.

4. 자주 하는 실수와 해결 #

4.1 들여쓰기로 인한 목록 깨짐

잘못된 예: 하위 항목 들여쓰기를 1칸이나 3칸으로 한 경우, 일부 렌더러에서 하위 항목으로 인식되지 않습니다.
❌ 잘못된 들여쓰기
- 상위 항목
 - 1칸 들여쓰기 (인식 안 됨)
   - 3칸 들여쓰기 (애매함)
✅ 올바른 들여쓰기 (2칸 또는 4칸)
- 상위 항목
  - 2칸 들여쓰기
  - 또 다른 하위 항목
    - 4칸 들여쓰기 (더 깊은 단계)

4.2 코드 블록 안에서 백틱 사용

코드 안에 백틱을 포함해야 한다면 4개 이상의 백틱으로 바깥을 감싸세요.

예시
````markdown
인라인 코드 예시: `print("hello")`

```python
print("hello")
```
````

4.3 표 정렬과 셀 안 줄바꿈

마크다운 표는 한 셀에 여러 줄을 넣을 수 없습니다. 줄바꿈이 필요하면 <br>을 직접 쓰거나, 표 대신 일반 목록으로 변환하세요.

4.4 한국어 헤더 앵커 깨짐

일부 도구는 한국어 제목으로 자동 생성된 앵커 링크를 깨뜨릴 수 있습니다. 중요한 섹션은 명시적 ID를 부여하세요.

예시 (HTML 호환)
## <a id="rules-create"></a>Rules 만들기

[이 섹션으로 이동](#rules-create)

4.5 특수 문자 이스케이프

마크다운 문법으로 해석되는 문자(* _ # [ ] ( ))를 그대로 출력하려면 백슬래시(\)로 이스케이프합니다.

예시
가격: \$100 (이스케이프 없으면 LaTeX 수식으로 해석될 수 있음)
별표 강조 없이 \*표시\* 그대로 출력

4.6 너무 깊은 헤더 계층

피해야 할 패턴: ###### 같은 6단계 헤더를 쓸 정도로 계층이 깊어지면 글의 구조가 잘못된 것입니다. 4단계(####) 이상은 새 파일로 분리하거나 목록으로 풀어쓰세요.

5. 한 페이지 치트시트 #

북마크해두고 필요할 때마다 참고하세요.

마크다운 핵심 문법 치트시트
기능 문법 예시
제목# ## ### ###### 섹션 제목
굵게**텍스트****중요한 규칙**
기울임*텍스트**부가 설명*
취소선~~텍스트~~~~삭제된 항목~~
인라인 코드`코드``pd.read_csv()`
코드 블록```언어
코드
```
```python
print("hi")
```
순서 없는 목록- 항목- 첫 번째
순서 있는 목록1. 항목1. 첫 단계
체크리스트- [x] / - [ ]- [x] 완료
링크[텍스트](URL)[공식 문서](https://...)
이미지![대체텍스트](경로)![다이어그램](./img.png)
인용> 텍스트> 중요한 메모
수평선------
| 헤더 |
| --- |
| 셀 |
본문 2.6 참조
이스케이프\문자\* 별표 그대로
다음 단계: 마크다운 기본기를 익혔다면 이제 실제 에이전트 설정에 적용해 보세요.

오늘코드 Antigravity 튜토리얼 — Google Antigravity 공식 문서 기반 한국어 학습 가이드

이 튜토리얼은 비공식 학습 자료입니다. 공식 문서: antigravity.google/docs

오늘코드