AI가 잘 읽는 Markdown 문서 구조 만들기

이 글에서 사용하는 주요 용어 정의

용어	정의
Markdown	일반 텍스트에 기호를 사용해 제목, 목록, 링크와 코드 구조를 표현하는 문법
헤딩 계층	#, ##, ###처럼 문서의 상하 관계를 나타내는 제목 구조
코드 펜스	세 개의 백틱으로 코드나 원문 범위를 분리하는 블록
입력·출력 계약	작업에 제공되는 자료와 결과가 가져야 할 형식을 명시한 규칙
CommonMark	Markdown의 모호한 해석을 줄이기 위해 정의된 공개 명세

---

도입

AI에게 긴 작업을 맡길 때 문장을 길게 쓰는 것보다 목표, 자료, 제약과 결과 형식을 구분하는 것이 중요합니다. Markdown은 이 경계를 일반 텍스트로 표현하기 쉬워 작업 명세와 프로젝트 문서에 잘 맞습니다.

Markdown을 쓴다고 AI의 정확도가 자동으로 올라가는 것은 아닙니다. 구조가 좋은 문서는 사람이든 AI든 무엇이 제목이고 예제이며 금지 조건인지 덜 혼동하게 만듭니다.

AI 작업 문서에 Markdown이 유용한 이유

정보의 계층을 표시한다

H1은 문서의 목적, H2는 주요 영역, H3는 세부 작업에 사용합니다. 제목 수준을 건너뛰지 않으면 독자와 AI가 같은 구조로 내용을 따라가기 쉽습니다.

# API 마이그레이션 작업

## 목표

## 현재 구조

### 인증
### 오류 처리

## 완료 조건

제목을 단순히 글씨를 크게 만드는 용도로 사용하지 마세요. 문서의 실제 포함 관계를 표현해야 합니다.

서로 다른 데이터 유형을 분리한다

설명, 명령, 코드와 기대 결과가 같은 문단에 섞이면 어떤 부분을 실행해야 하는지 모호해집니다. 코드 펜스에 언어 이름을 붙이면 경계를 더 분명하게 만들 수 있습니다.

npm test

기대 결과: 모든 단위 테스트 통과

반복되는 항목을 비교하기 쉽다

표는 필드가 반복되는 비교에 적합합니다. 역할, 입력, 출력처럼 같은 기준으로 여러 항목을 비교할 때 사용하세요.

역할	입력	출력
리서처	주제	근거와 개요
작성자	리서치	원고
검수자	리서치와 원고	QA 보고서

한 셀에 긴 문단을 넣어야 한다면 표보다 소제목이 낫습니다.

핵심 내용

문서 첫부분에 목표를 한 문장으로 쓴다

배경을 길게 설명하기 전에 최종 결과를 먼저 적습니다.

# 목표

기존 REST API를 유지하면서 `/v2` 응답 형식을 추가하고 단위 테스트를 통과시킨다.

"코드를 개선한다"보다 대상과 완료 상태가 구체적입니다.

현재 상태와 원하는 상태를 나눈다

AI가 기존 동작을 새 요구사항으로 오해하지 않도록 두 상태를 분리합니다.

## 현재 상태

- `/v1/users`만 제공
- 오류 응답이 문자열

## 원하는 상태

- `/v2/users` 추가
- 오류 응답을 `{ code, message }`로 통일
- `/v1` 동작 유지

제약과 금지 사항을 별도 섹션에 둔다

중요한 제한을 여러 문단에 흩뿌리지 마세요. 한곳에서 충돌 여부를 확인할 수 있어야 합니다.

## 제약

- 데이터베이스 스키마를 변경하지 않는다.
- 새로운 런타임 의존성을 추가하지 않는다.
- 외부 API를 실제 호출하지 않는다.

완료 조건은 관찰 가능한 상태로 쓴다

"잘 동작해야 한다"는 검증하기 어렵습니다. 파일, 테스트, HTTP 상태처럼 확인할 수 있는 결과를 적으세요.

## 완료 조건

- `npm test`가 종료 코드 0으로 끝난다.
- 기존 `/v1` 테스트가 유지된다.
- `/v2` 성공·실패 테스트가 추가된다.

나쁜 문서와 좋은 문서 비교

모호한 요청

이 프로젝트를 보고 API를 최신 방식으로 잘 바꿔줘. 테스트도 해줘.

무엇을 최신으로 보는지, 호환성을 유지해야 하는지, 어떤 테스트가 필요한지 알 수 없습니다.

구조화한 요청

# 목표
사용자 조회 API에 `/v2` 응답을 추가한다.

## 유지할 동작
- `/v1/users` 응답과 상태 코드

## 변경할 동작
- `/v2/users`는 `{ data, error }` 구조 사용

## 검증
- 기존 테스트 실행
- `/v2` 성공, 인증 실패, 사용자 없음 테스트 추가

## 권한
- 저장소 파일 수정과 테스트 실행 허용
- 배포와 외부 전송 금지

두 번째 요청은 모델에게 더 많은 문장을 주기보다 결정에 필요한 경계를 제공합니다.

실제 적용과 한계

Markdown 파서마다 세부 동작이 다를 수 있습니다. Tistory, GitHub와 CommonMark가 표나 줄바꿈을 동일하게 처리한다고 가정하지 말고 대상 플랫폼에서 미리보기로 확인하세요.

문서가 구조적이어도 사실이 틀리면 결과도 틀릴 수 있습니다. 최신 API, 숫자와 일정은 출처를 함께 제공하고, 실행 권한과 완료 조건은 별도로 검증해야 합니다.

마무리

AI가 읽기 쉬운 Markdown은 화려한 문법보다 명확한 경계가 중요합니다. 하나의 H1, 순서가 맞는 H2/H3, 언어가 표시된 코드 펜스, 짧은 표와 관찰 가능한 완료 조건을 사용하세요.

다음에 긴 요청을 입력하기 전에 내용을 목표, 현재 상태, 제약, 완료 조건 네 부분으로만 나눠 보세요. 같은 내용을 반복 설명하는 횟수가 줄어듭니다.

참고 자료

• CommonMark 0.31.2 Specification
• GitHub Docs - Writing on GitHub