AI가 “코드 읽기”를 넘어서 “이해”하게 만드는 방법: `/w-context`로 CONTEXT.md 자동 생성하기

시리즈 안내

순서	제목	내용
1편	Claude Code Commands로 개발 워크플로우 자동화하기	전체 개요
2편	/spec - 명세서 기반 코드 구현 자동화	가장 핵심인 구현 자동화
3편	/create-jest - 테스트 코드 자동 생성	테스트 작성 자동화
4편	/w-context - AI를 위한 문서 작성	CONTEXT.md 개념과 활용 (현재 글)
5편	/pr + /apply-review - PR 워크플로우 자동화	PR 생성부터 리뷰 반영까지

---

들어가며

Claude Code를 쓰다 보면 이런 상황, 은근 자주 마주칩니다.

• “이 폴더 구조 왜 이렇게 돼 있어?” → Claude: (모든 파일을 읽으며 추론 시작…)
• “여기에 기능 추가해줘” → Claude: (구현은 했는데 기존 패턴이랑 미묘하게 다름)
• “이 모듈 어떻게 쓰는 거야?” → Claude: (코드 분석은 하는데 ‘설계 의도’는 알 수 없음)

AI는 코드를 읽을 수는 있어요.
그런데 코드를 이해하려면 결국 맥락이 필요합니다.

그래서 만든 게 /w-context입니다.

AI가 읽을 수 있는 README를 자동으로 만들어주는 명령어.
코드 주석 대신, 설계 의도와 사용 패턴을 한 곳에 모아두는 문서화 방식.

---

CONTEXT.md가 뭔가요?

한 문장으로 하면 이렇습니다.

AI를 위한 모듈 설명서입니다.

README.md가 “사람”에게 설치/사용/기여 방법을 알려주는 문서라면,
CONTEXT.md는 “AI가 이 폴더를 처음 볼 때 반드시 알아야 할 것”에 집중합니다.

README vs CONTEXT

구분	README.md	CONTEXT.md
대상	개발자(사람)	AI 어시스턴트
목적	설치/사용법/운영	설계 의도/맥락/패턴 전달
위치	보통 루트	모듈(폴더)별
핵심 질문	어떻게 쓰지? (How)	왜 이렇게 만들었지? (Why)

여기서 핵심은 딱 하나예요.

AI가 흔히 놓치는 건 구현력이 아니라, “왜 이렇게 했는지”입니다.

---

/w-context가 하는 일

실행은 한 줄입니다.

/w-context

그러면 Claude가 현재 작업 중인 폴더를 기준으로 CONTEXT.md를 생성(또는 업데이트)합니다.

1. 폴더 파악 — 지금 작업하는 모듈이 무엇인지 확인
2. 파일 분석 — 코드 구조/역할/패턴을 읽어냄
3. 기존 문서 확인 — CONTEXT.md가 있으면 업데이트, 없으면 생성
4. CONTEXT.md 작성 — 팀 규칙에 맞춰 문서화

중요한 건 이게 “한 번 만들고 끝”이 아니라는 점이에요.

코드가 바뀌면 /w-context를 다시 실행해서
문서도 같이 최신화합니다.

문서가 최신 상태로 유지되면, AI가 같은 모듈을 수정할 때 “처음 보는 프로젝트”처럼 헤매지 않게 됩니다.

---

CONTEXT.md에는 무엇을 넣나요?

저는 CONTEXT.md를 5개 섹션으로 고정했습니다.
이 정도면 AI가 맥락을 잡기에 충분하면서, 과하게 길어지지도 않더라고요.

---

1) 이 모듈이 하는 일 (한 문장으로 끝)

## 이 모듈이 하는 일

HTTP 요청을 표준화된 방식으로 처리하고, 인증/재시도/에러 핸들링을 자동화합니다.

이 한 줄이 있으면 AI는 첫 줄에서 이렇게 판단합니다.

“아, 이 폴더는 API 클라이언트 레이어구나.”

이게 없으면 Claude는 “파일 다 읽고 추론”부터 시작해요.
작업 속도가 달라질 수밖에 없습니다.

---

2) 파일 구조와 역할 (어디를 고쳐야 하는지 바로 보이게)

## 파일 구조와 역할

- `client.ts`: 핵심 HTTP 클라이언트, fetch 래핑, 재시도 로직
- `types.ts`: 요청/응답 타입 정의
- `interceptors.ts`: 요청/응답 인터셉터
- `index.ts`: public API 내보내기

이 섹션이 있으면 “수정 지점”을 찾는 시간이 줄어요.

• 재시도 로직 추가? → client.ts
• 에러 타입 추가? → types.ts
• public export 변경? → index.ts

AI도 사람이랑 똑같이 “어디부터 볼지”가 중요합니다.

---

3) 핵심 설계 결정 (가장 중요한 파트: Why)

이게 CONTEXT.md의 진짜 목적입니다.
AI가 기존 방향을 존중하게 만드는 장치예요.

## 핵심 설계 결정

1. **fetch 직접 래핑**
   - axios 대신 네이티브 fetch 사용
   - 번들 사이즈 최소화
   - React Native/Web에서 동일하게 동작

2. **재시도는 네트워크 에러만**
   - 4xx는 재시도하지 않음
   - 비즈니스 에러는 재시도해도 결과가 같음
   - 불필요한 서버 부하 방지

3. **토큰 자동 주입**
   - 모든 요청에 인증 헤더 자동 추가
   - 호출부에서 토큰 관리 코드 제거
   - 토큰 갱신 로직 중앙화

이런 내용이 없으면 AI는 보통 “자기가 생각하는 베스트 프랙티스”로 구현하려고 합니다.
그게 항상 틀린 건 아니지만, 프로젝트의 의도와 다를 수 있어요.

---

4) 사용 패턴 (AI가 ‘복붙’할 수 있는 예시)

## 사용 패턴

```ts
import { apiClient } from "@/libs/api";

// GET
const users = await apiClient.get<User[]>("/users");

// POST
const newUser = await apiClient.post<User>("/users", {
  body: { name: "John", email: "john@example.com" }
});

// 에러 처리
try {
  await apiClient.get("/protected");
} catch (error) {
  if (error instanceof ApiError) {
    // 401이면 로그아웃 처리
  }
}

AI는 “예시 코드”를 굉장히 잘 따릅니다.  
즉, 사용 패턴 섹션은 **미래의 코드 스타일을 유도하는 템플릿**이에요.

---

### 5) 확장 시 고려사항 (미리 알려주면 삽질이 줄어든다)

```md
## 확장 시 고려사항

- 새 HTTP 메서드 추가 시 `client.ts`의 request 메서드 확장
- 인터셉터 추가 시 실행 순서 주의 (요청은 정순, 응답은 역순)
- 에러 타입 추가 시 `types.ts`의 ApiError 클래스 확장
- 캐싱 도입 시 React Query와의 역할 분리 고려

이게 없으면 AI가 기능 추가하면서 “좋아 보이는 방향”으로 확장하는데,
그게 나중에 구조를 망가뜨리는 경우가 있어요.

확장 포인트를 미리 적어두면, AI가 안전한 레일 위에서 움직입니다.

---

실제 생성 결과 예시 (libs/api/에서 실행하면)

libs/api/ 폴더에서 /w-context를 실행하면 대략 이런 문서가 생깁니다.

# API 클라이언트 컨텍스트

이 문서는 AI가 api 모듈의 설계 의도와 사용 방법을 빠르게 파악할 수 있도록 작성되었습니다.

## 이 모듈이 하는 일
HTTP 요청을 표준화된 방식으로 처리하고, 인증 토큰 관리와 에러 핸들링을 자동화합니다.

## 파일 구조와 역할
- `client.ts`: fetch 래핑, 재시도 로직
- `types.ts`: 요청/응답 타입, 에러 클래스
- `auth/`: 인증 관련 API
- `user/`: 사용자 관련 API
- `index.ts`: public API export

## 핵심 설계 결정
- axios 대신 fetch 사용
- 네트워크 에러만 재시도 (지수 백오프)
- ApiError로 에러 표준화

## 사용 패턴
(예시 코드...)

## 확장 시 고려사항
- 도메인별 폴더로 분리 (`links/`, `folders/`)
- 캐싱은 React Query에서 처리

이 문서 하나만 있으면 AI는 “추측”이 아니라 “이해”를 기반으로 움직이게 됩니다.

---

기존 CONTEXT.md가 있으면? 덮어쓰지 않고 “동기화”합니다

문서 자동 생성의 최대 단점은 이거죠.

“내가 손으로 다듬은 내용이 날아갈까 봐 무섭다”

그래서 /w-context는 “갈아엎기”가 아니라 “동기화”로 설계했습니다.

1. 기존 CONTEXT.md 구조는 유지
2. 코드 변경사항 분석
3. 새 파일/기능은 추가 반영
4. 삭제된 요소는 문서에서 제거
5. 설계 결정/사용 패턴이 바뀌면 해당 섹션만 업데이트

즉, 문서를 코드와 같은 생명주기로 관리합니다.

---

왜 코드 주석 대신 CONTEXT.md인가?

주석으로도 설명할 수는 있어요.
그런데 저는 CONTEXT.md가 “AI 시대에는” 더 실용적이라고 느꼈습니다.

주석의 한계

// 재시도 로직
// - 네트워크 에러만 재시도
// - 최대 3회
// - 지수 백오프 적용
async function fetchWithRetry() {}

• 파일 곳곳에 흩어져 있음
• 전체 설계 그림이 한눈에 안 보임
• AI가 맥락 파악하려면 여러 파일을 다 읽어야 함

CONTEXT.md의 장점

• 한 곳에 모인다 → 맥락을 빠르게 로딩
• Why 중심 → 설계 의도를 명시
• AI 친화적 → 한 번에 읽고 이해 가능
• 유지보수 쉬움 → 코드와 분리, 업데이트도 명령어로

한마디로, 주석은 “로컬 설명”, CONTEXT는 “모듈의 지도”입니다.

---

저는 언제 /w-context를 실행하나요?

저는 아래 타이밍을 루틴으로 만들었습니다.

1) 새 모듈을 만들었을 때

mkdir libs/cache
# 코드 작성...
/w-context

2) 기존 모듈을 크게 수정했을 때

# libs/api 구조 변경
/w-context

3) /spec으로 구현을 끝낸 직후

/spec user-profile
/w-context

구현 직후가 설계 의도가 가장 선명할 때라 문서 품질이 좋아요.

4) PR 올리기 직전

/w-context
/pr

PR에서 “문서 최신인가?”를 사람이 체크하지 않게 만들기.

---

CONTEXT.md는 어디에 생기나요?

현재 작업 중인 폴더 내부에 CONTEXT.md로 생성됩니다.

libs/
├── api/
│   ├── client.ts
│   ├── types.ts
│   └── CONTEXT.md
├── logger/
│   └── CONTEXT.md
└── utils/
    └── CONTEXT.md

모듈별로 하나씩 있으면, AI가 특정 폴더를 작업할 때 그 폴더의 맥락만 빠르게 읽고 들어올 수 있어요.
(프로젝트 전체 README 한 장으로는 절대 못 하는 일입니다.)

---

커스터마이징 포인트

프로젝트 성격에 따라 CONTEXT.md 템플릿을 바꿀 수 있어요.

1) 필수 섹션 추가

## 필수 포함 내용
1. 이 모듈이 하는 일
2. 파일 구조와 역할
3. 핵심 설계 결정
4. 사용 패턴
5. 확장 시 고려사항
6. 성능 고려사항 (선택)
7. 보안 관련 사항 (선택)

2) 작성 언어

영어 프로젝트면 작성 언어만 바꾸면 됩니다.

- Use English for all sections
- Keep it concise and technical

3) 생성 위치 변경

모듈 안이 아니라, docs로 모아도 됩니다.

- `docs/context/{module}.context.md`에 생성

---

/spec, /create-jest와 붙이면 “개발 3종 세트”가 됩니다

/spec user-notification
/create-jest
/w-context

이렇게 하면

• 구현은 명세서 기반으로 일관되게
• 테스트는 자동으로 따라오고
• 맥락은 문서로 남아서 다음 작업 품질이 올라갑니다

즉, 한 번 만든 모듈이 시간이 지나도 “설계 의도”를 잃지 않게 돼요.

---

왜 이 방식이 효과적이었나

1. AI의 맥락 부족 문제 해결
   코드만 보면 AI는 추측할 수밖에 없는데, CONTEXT.md가 있으면 확신을 갖고 작업합니다.

2. 온보딩 시간 단축
   새 팀원, 새 AI 세션 모두 “CONTEXT부터 읽고 시작”이 가능해집니다.

3. 일관된 코드 스타일 유지
   설계 결정과 사용 패턴이 문서화되어 있으니, 사람이든 AI든 같은 방향으로 코드를 씁니다.

4. 미래의 나를 위한 보험
   3개월 뒤 “왜 이렇게 했지?”라는 질문에 CONTEXT.md가 답해줍니다.

---

주의사항

1) 모든 폴더에 만들 필요는 없습니다

단순 UI 컴포넌트까지 CONTEXT.md를 만들면 오히려 노이즈가 됩니다.
복잡한 로직/규칙이 있는 모듈에만 집중하는 게 좋아요.

2) 코드와 문서의 동기화가 핵심입니다

문서가 코드와 달라지면 혼란을 줍니다.
큰 변경 후에는 /w-context로 업데이트하는 습관이 중요해요.

3) 민감 정보는 절대 쓰지 마세요

API 키, 내부 보안 규칙, 인증 우회 힌트 같은 건 문서에 남기면 안 됩니다.
“설계 의도”와 “비밀 정보”는 다릅니다.

---

실제 명령어 파일은 이렇게 생겼습니다 (핵심만)

# w-context.md

현재 작업 중인 폴더에 CONTEXT.md 파일을 생성하거나 업데이트합니다.

## 목적
AI가 해당 모듈의 맥락을 빠르게 파악할 수 있도록 자연어 문서를 작성합니다.

## 실행 방법
1. 현재 폴더 확인
2. 폴더 내 파일 분석
3. CONTEXT.md 존재 여부 확인
   - 없으면 생성
   - 있으면 변경사항 동기화

## CONTEXT.md 작성 규칙
### 필수 포함
1. 이 모듈이 하는 일
2. 파일 구조와 역할
3. 핵심 설계 결정
4. 사용 패턴
5. 확장 시 고려사항

### 작성 원칙
- 코드를 읽지 않아도 이해 가능해야 함
- 구현 디테일보다 의도/맥락 중심
- 핵심만 간결하게

---

마치며

/w-context의 핵심은 이거였습니다.

AI가 코드를 “읽는” 수준에서 멈추지 않고,
“이해하고 같은 방향으로 수정”하도록 돕는 것.

처음엔 “문서 또 써야 해?” 싶을 수 있어요.
근데 /w-context는 한 줄이고, 효과는 꽤 큽니다.

다음 5편에서는 /pr과 /apply-review로
PR 생성부터 리뷰 반영까지 워크플로우를 자동화한 이야기를 정리해볼게요.

---

참고: Link Dropper 프로젝트

이 글에서 소개한 명령어들은 제가 만들고 있는 Link Dropper 프로젝트에서 실제로 사용하고 있습니다.

• App Store에서 다운로드하기
• 웹에서 사용하러 가기
• 크롬 익스텐션 설치하기