1. 서론: 왜 AI는 당신의 문서를 읽지 못하는가
AI 코딩 도구의 시대가 도래했습니다. Cursor, GitHub Copilot, Claude Code와 같은 AI 에이전트들이 개발자의 일상에 깊숙이 자리 잡고 있지만, 많은 개발자들이 “왜 AI가 내 문서를 제대로 읽지 못할까?”라는 질문을 던집니다. 문제의 핵심은 우리가 인간을 위해 작성한 문서가 AI에게는 최적화되어 있지 않다는 점입니다.
AI 에이전트는 인간과 다른 방식으로 정보를 처리합니다.
•
벡터 데이터베이스를 통한 의미론적 검색
•
컨텍스트 윈도우의 제한
•
명시적 지침에 대한 의존성
이 글에서는 AI 코딩 에이전트가 효과적으로 이해하고 활용할 수 있는 마크다운 문서 작성법을 다룹니다. 단순히 “많은 문서”가 아니라 “AI 친화적인 문서”를 만드는 방법을 설명합니다.
2. AI 친화적 문서화의 핵심 원칙
2.1. 원칙 1: 가정을 줄여라 (Reduce Assumptions)
•
AI는 비즈니스 도메인 지식이나 암묵적 컨벤션을 추론하기 어렵습니다.
•
실천 방법
◦
표준화된 추상화 사용
◦
타입이 명확한 언어 활용 (TypeScript, Kotlin 등)
◦
축약어보다 전체 단어 사용
◦
메인스트림 프레임워크 채택
•
예시
// ❌ 나쁜 예
class UsrMgr {
fun proc(u: Usr) { ... }
}
// ✅ 좋은 예
class UserManager {
fun processUserRegistration(user: User) { ... }
}
Kotlin
복사
2.2. 원칙 2: 컨텍스트를 줄여라 (Reduce Context)
•
AI는 한 번에 인식할 수 있는 정보(컨텍스트 윈도우)가 제한되어 있습니다.
•
핵심 전략
◦
한 페이지 원칙: 워크플로우는 단일 문서로 설명 가능해야 함
◦
관련 변경사항 집중화
◦
모듈형 아키텍처
◦
임베디드 문서 선호 (코드 근처 주석)
•
디렉토리 예시
❌ 나쁜 예
/docs/user-service/overview.md
/docs/user-service/authentication.md
/docs/user-service/database-schema.md
✅ 좋은 예
/services/user/README.md # 모든 필수 정보 포함
Plain Text
복사
3. AI 친화적 마크다운 작성 패턴
3.1. 패턴 1: 파일 상단의 의미론적 설명
•
왜 중요한가
◦
AI IDE(Copilot, Cursor 등)는 파일 상단의 주석을 벡터로 임베딩하여 의미를 학습합니다.
•
템플릿 예시
/**
* UserAuthenticationService.kt
*
* 목적: 사용자 인증 및 세션 관리를 담당
*
* 주요 기능:
* - JWT 로그인/로그아웃
* - 리프레시 토큰 갱신
* - Role-based 권한 검증
*
* 수정 시점:
* - OAuth 추가 시
* - 만료 정책 변경 시
*
* 의존성:
* - UserRepository
* - TokenProvider
* - RedisSessionStore
*/
Kotlin
복사
3.2 패턴 2: 모든 출력을 “프롬프트”로 만들기
•
나쁜 예
Error: Database connection failed
Plain Text
복사
•
좋은 예
Database connection failed
What went wrong:
Could not connect to PostgreSQL at localhost:5432
How to fix:
1. Check if PostgreSQL is running: `docker ps | grep postgres`
2. Verify connection string in .env
3. Ensure database exists: `psql -l`
Next steps:
Run `./scripts/init-db.sh`
Plain Text
복사
3.3. 패턴 3: Self-Documenting 코드 구조
./gradlew runMigration --args="--env=dev --version=1.2.3"
Options:
--env Environment (dev, staging, prod)
--version Migration version
--dry-run Preview only
Bash
복사
3.4. 패턴 4: 워크플로우 중심 구조
•
AI가 어려워하는 구조
/controllers
/services
/repositories
Plain Text
복사
•
AI가 잘 이해하는 구조
/features
/user-authentication
/backend
UserAuthService.kt
UserRepository.kt
/frontend
LoginForm.tsx
useAuth.ts
/tests
auth.test.ts
README.md
Plain Text
복사
3.5 패턴 5: 은유적 인터페이스 활용
•
AI는 익숙한 패턴을 잘 이해합니다.
@Test
fun `test_user_creation_with_valid_data`() { ... }
Kotlin
복사
3.6. 패턴 6: 프로그래밍 방식의 검증
•
.github/workflows/ai-validation.yml
name: AI Code Validation
on: [push, pull_request]
jobs:
validate:
steps:
- name: Type Check
run: ./gradlew compileKotlin
- name: Lint Check
run: ./gradlew ktlintCheck
- name: Unit Tests
run: ./gradlew test
- name: Security Scan
run: ./gradlew dependencyCheckAnalyze
YAML
복사
4. Cursor Rules 작성 모범 사례
4.1. Cursor Rules란
•
.cursorrules는 AI에게 프로젝트별 규칙을 알려주는 AI용 가이드라인 파일입니다.
4.2. 작성 원칙
1.
명령이 아닌 참고자료로 작성
2.
설명적인 이름과 요약
3.
“무엇”에 집중, “어떻게”는 최소화
4.
코드 파일과 링크로 연결
•
예시
◦
규칙이 많다는 건 코드베이스가 AI 친화적이지 않다는 신호입니다.
# Error Handling
All services use standardized error handling:
- See [BaseService.kt](../services/BaseService.kt)
- Custom exceptions: [exceptions/](../exceptions/)
- Error response: [ErrorResponse.kt](../models/ErrorResponse.kt)
Markdown
복사
5. 파일 구조 최적화
5.1. 파일 크기 관리
•
파일당 500줄 이하
•
단일 책임 원칙
•
기능 단위 분할
5.2. 고유한 파일명 사용
❌ /pages/user/page.js
✅ /pages/user/UserListPage.js
Plain Text
복사
5.3. 컨텍스트 명시
@folder src/features/authentication
이 폴더의 로그인 로직을 OAuth로 변경해줘
Plain Text
복사
6. 문서 구조 템플릿
6.1. 프로젝트 루트 README.md
# MAIN API
## 빠른 시작
docker-compose up -d
./gradlew bootRun
## 아키텍처 개요
(간단한 다이어그램 또는 설명)
## 주요 기능
| 기능 | 위치 | 담당자 |
|------|------|--------|
| 사용자 인증 | ./features/auth | @username |
| 결제 처리 | ./features/payment | @username |
## 개발 가이드
- ./docs/coding-conventions.md
- ./docs/api-design.md
## 배포
./scripts/deploy.sh --env=staging
## 트러블슈팅
문제: Database connection timeout
해결: [link to solution]
Markdown
복사
6.2 기능별 README.md
# 사용자 인증 기능
## 개요
JWT 기반 인증 (Access 15분 + Refresh 7일)
## 파일 구조
/features/auth
/backend
AuthController.kt
AuthService.kt
/frontend
LoginPage.tsx
useAuth.ts
/tests
AuthIntegrationTest.kt
Markdown
복사
7. CLI vs MCP: 인터페이스 선택
구분 | CLI | MCP |
장점 | 단순, 명령 조합 쉬움 | 구조적, 타입 안전 |
적합한 경우 | 스크립트, 빌드 | IDE 통합, 복잡한 데이터 |
단점 | 제한적 구조 | 설정 복잡 |
8.실전 체크리스트
8.1. 문서 작성 시
•
파일 상단에 목적/기능 명시
•
단일 문서로 워크플로우 정리
•
코드 예시는 실제 동작 가능한 형태로
•
에러 메시지에 해결책 포함
8.2. 코드 구조 시
•
파일당 500줄 이하
•
고유 파일명
•
기능별 폴더 구조
•
Self-documenting 네이밍
8.3. 개발 환경 시
•
강력한 린터 설정
•
다층 테스트 전략
•
명확한 에러 메시지
8.4. Cursor Rules 시
•
명령 X, 참고자료 O
•
실제 코드 링크 포함
•
규칙 최소화
9. 결론: AI 시대의 개발자 역할 변화
AI는 개발자를 대체하지 않습니다. 대신 아키텍트, 품질 관리자, 시스템 디자이너로서의 역할을 강화합니다.
•
구현보다 설계에 집중
•
AI가 이해할 수 있는 구조 설계
•
Self-documenting 코드 구축