AI 프로젝트 맥락 패키지를 만드는 방법
Claude Code, Cursor, Codex, ChatGPT가 프로젝트를 다시 이해할 수 있도록 규칙, 결정, 링크, 저장 대화를 묶는 실무 가이드입니다.
2026년 5월 6일
AI 프로젝트 맥락 패키지는 AI 도구가 프로젝트를 도와주기 전에 알아야 할 규칙, 결정, 링크, 저장 대화를 묶은 짧은 안내서입니다. 매번 Claude Code, Cursor, Codex, ChatGPT에 같은 설명을 반복하지 않기 위한 작업 자료입니다.
Highlight Reel
다시 쓸 AI 프로젝트 맥락을 저장하세요
중요한 AI 대화와 결정 흐름을 Highlight Reel에 남기고, 팀과 미래의 AI 도구가 읽을 수 있는 자료로 정리하세요.
좋은 맥락 패키지는 원본 대화 전체를 복사한 파일이 아닙니다. 안정된 프로젝트 규칙, 현재 상태, 중요한 결정, 다시 읽어야 할 AI 대화 링크를 나누어 둔 구조입니다.
먼저 결론부터
AI 프로젝트 맥락 패키지는 다섯 가지 질문에 답해야 합니다.
- 이 프로젝트는 무엇인가?
- 이미 결정된 것은 무엇인가?
- AI가 따라야 할 규칙은 무엇인가?
- 먼저 읽어야 할 파일, 링크, 저장 대화는 무엇인가?
- AI가 하지 말아야 할 일은 무엇인가?
도구별 파일은 얇게 유지하세요. Claude Code의 CLAUDE.md, Cursor rules, Codex의 AGENTS.md는 핵심 규칙과 링크를 안내하고, 자세한 맥락은 공유 패키지나 저장 대화로 보내는 편이 관리하기 쉽습니다.
맥락 패키지가 필요한 이유
AI 도구는 강력하지만 프로젝트 맥락을 잃기 쉽습니다. 어제 설명한 제품 방향, 지난주 결정한 코드 규칙, 방금 고친 배포 문제를 새 세션이 모르는 경우가 많습니다.
맥락 패키지는 다음 문제를 줄입니다.
- 같은 프로젝트 설명을 반복하는 시간
- 이미 버린 방향을 다시 제안받는 일
- 중요한 결정이 채팅 기록 속에 묻히는 일
- 도구마다 다른 지침을 유지하는 혼란
- AI가 읽으면 안 되는 정보까지 붙여 넣는 위험
무엇을 넣을까
| 섹션 | 넣을 내용 | 관리 팁 |
|---|---|---|
| 프로젝트 요약 | 제품, 사용자, 핵심 흐름, 현재 단계 | 안정된 설명으로 작성 |
| 출처 | repo, 문서, 대시보드, 저장 대화 | 원본 링크를 유지 |
| 결정 | 구조 선택, 포지셔닝, 버린 방향 | 이유와 날짜를 남김 |
| 작업 규칙 | 코드 스타일, 테스트, 글쓰기 톤 | 관찰 가능한 규칙으로 작성 |
| 도구 지침 | CLAUDE.md, Cursor rules, AGENTS.md | 얇게 두고 공유 문서를 가리킴 |
| 안전 경계 | 비밀값, 게시, 삭제, 배포 | 확인이 필요한 행동을 명시 |
기본 템플릿
# AI Project Context Packet
Last reviewed: <date>
Owner: <person or team>
## Project Snapshot
- Product:
- Audience:
- Primary workflow:
- Current stage:
- What success looks like:
## Source Of Truth
- Repo:
- Product docs:
- Admin/dashboard:
- Saved AI conversations:
## Decisions
- <date>: <decision> — <why it matters>
## Working Rules
- Code:
- Tests:
- Writing:
- Review:
## Do Not Do Without Confirmation
- Delete data
- Publish content
- 운영 비밀값 교체
- Change billing or infra저장 대화는 어디에 넣을까
중요한 AI 대화는 패키지 본문에 전부 붙이지 마세요. 대신 제목, 한 줄 요약, 왜 읽어야 하는지, 링크를 남기세요.
예시:
| 저장 대화 | 왜 읽어야 하나 |
|---|---|
| Blog localization pilot | 일본어/한국어 용어와 이미지 줄바꿈 규칙 |
| MCP connector design | 제품이 MCP로 노출할 자료와 권한 경계 |
| SEO article workflow | draft-only 원칙, references, CTA, media QA |
MCP와 연결하는 경우
패킷이 많아지면 AI 클라이언트가 필요한 자료를 직접 검색하고 가져오게 만들 수 있습니다. 이때 MCP가 유용합니다. MCP는 AI 앱이 외부 시스템의 자료나 도구를 사용할 수 있게 하는 표준입니다.
단, MCP 연결은 정리되지 않은 자료를 자동으로 좋은 지식으로 바꾸지 않습니다. 제목, 요약, 접근 범위, 민감 정보 확인이 먼저입니다.
Highlight Reel을 쓰는 경우
Highlight Reel은 중요한 AI 대화와 결정 흐름을 재사용 가능한 링크로 남길 때 맞습니다. 프로젝트 맥락 패키지 안에서 "이 대화를 먼저 읽어야 한다"는 링크로 사용할 수 있습니다.
자주 묻는 질문
모든 프로젝트에 맥락 패키지가 필요한가요?
작은 일회성 작업에는 필요 없습니다. 반복적으로 AI 도구를 쓰거나, 여러 도구와 팀원이 같은 맥락을 공유해야 할 때 유용합니다.
패킷이 너무 길어지면 어떻게 하나요?
핵심 파일은 짧게 유지하고, 세부 내용은 링크로 분리하세요. 오래된 현재 상태는 정리하거나 날짜가 붙은 기록으로 옮기세요.
AGENTS.md와 같은 건가요?
아닙니다. AGENTS.md는 Codex 같은 도구가 읽는 repo 지침에 가깝고, 맥락 패키지는 프로젝트 맥락 전체를 다루는 공유 자료입니다. 서로 연결해서 쓰면 좋습니다.
정리하면
AI 프로젝트 맥락 패키지는 AI에게 매번 같은 설명을 반복하지 않기 위한 작업 기반입니다. 안정된 규칙, 현재 상태, 결정, 저장 대화를 나누어 두면 여러 AI 도구가 같은 맥락에서 시작할 수 있습니다.