좋은 Context는 어떻게 만들까? AI 코딩 실전 원칙 7가지
AI에게 일을 맡겼는데 첫 답은 그럴듯하지만 프로젝트의 규칙을 놓치거나, 매번 같은 설명을 반복하게 되는 일이 있다. 모델이 충분히 똑똑하지 않아서만은 아니다. 대개는 Context(맥락)가 흐릿하기 때문이다.
Context는 AI에게 주는 ‘작업 설명서와 현장 지도’다. 지도 없이 “맛집 찾아줘”라고 하면 유명한 곳만 말하지만, 동네·예산·인원·알레르기를 알려주면 현실적인 선택을 한다. 코딩 에이전트도 같다.
좋은 Context는 많이 넣은 정보가 아니라, 이번 판단에 필요한 사실을 정확한 위치에 둔 정보다.
1. 작업 목표와 ‘완료’를 함께 적는다
“로그인 기능 만들어줘”는 출발점일 뿐이다. 어떤 화면에서, 무엇을 허용하고, 테스트가 통과하면 끝인지가 있어야 AI도 같은 결승선을 본다.
| 나쁜 요청 | 좋은 요청 |
|---|---|
| 로그인 만들어줘 | Next.js 앱에 이메일 로그인 화면을 추가해줘. 기존 디자인 토큰을 쓰고, 로그인 실패 문구는 한국어로 표시해줘. npm test와 npm run lint가 통과하면 완료야. |
2. 변하지 않는 규칙은 파일로, 오늘의 일은 대화로
매번 말해야 하는 규칙은 대화창이 아니라 저장소의 AGENTS.md에 둔다. Codex 공식 가이드는 이 파일에 프로젝트 구조, 실행·빌드·테스트 명령, 코딩 관례, 금지 사항, 완료 기준을 담으라고 권한다. 특히 짧고 정확한 파일이 길고 모호한 파일보다 낫다고 설명한다. OpenAI Codex Manual
Claude Code에서는 같은 역할을 CLAUDE.md가 맡는다. Claude의 공식 문서도 “매 세션마다 다시 설명할 사실”만 적고, 반복 실수가 두 번째 생길 때 추가하라고 권한다. 구체적이고 간결하게 쓸수록 잘 지켜진다. Claude Code 문서
# AGENTS.md
- 패키지 매니저는 pnpm만 사용한다.
- 변경 전 관련 테스트를 먼저 찾는다.
- API 응답 형식 변경 시 OpenAPI 스키마와 테스트를 함께 수정한다.
- 완료 전: pnpm lint && pnpm test3. 배경 설명보다 ‘사실의 출처’를 연결한다
AI에게 문서 내용을 길게 복사하기보다, 최신 기획서·API 명세·결정 기록을 프로젝트의 자료로 넣고 “이 문서를 기준으로 하라”고 지정한다. ChatGPT Project는 파일과 프로젝트별 지침을 추가할 수 있다. 프로젝트 전용 메모리를 선택하면 맥락의 경계도 분명해진다. OpenAI Projects 안내
“최신 문서는
/docs/decision-log.md이고, 충돌하면 이 문서가 우선”처럼 정답의 원본과 우선순위를 알려주면 오래된 설명이 섞일 위험이 줄어든다.4. 기억은 편의 기능이지, 단일 진실이 아니다
ChatGPT Memory는 이전 대화·파일·연결된 앱에서 유용한 정보를 기억해 반복 설명을 덜어 준다. 하지만 메모리 요약에는 모든 정보가 들어가지 않을 수 있다. 제품의 가격, 배포 주소, 보안 정책처럼 틀리면 문제가 되는 사실은 현재 프로젝트 문서나 이번 요청에 다시 명시하는 편이 안전하다. OpenAI Memory FAQ
“예전에 AI가 기억한 오래된 배포 URL 때문에 잘못된 환경을 수정하려 했던 사례”처럼 실제 경험이 있다면 2~3문장으로 추가해 보자. 독자가 Context를 관리해야 하는 이유를 바로 이해한다.
5. 큰 작업은 ‘지도 → 구역 → 실행’으로 나눈다
한 번에 모든 파일과 요구를 던지면 중요한 조건이 묻힌다. 먼저 현재 구조와 영향 범위를 파악하게 하고, 계획을 검토한 뒤, 구현과 테스트를 시킨다. 새 화면이라면 “관련 컴포넌트와 테스트 위치를 먼저 찾아 5줄 계획을 보여줘”라고 시작하면 된다.
6. 도구는 능력을 늘리지만, 권한과 범위를 먼저 정한다
MCP(Model Context Protocol)는 AI 앱을 파일·데이터베이스·검색·업무 도구에 연결하는 공개 표준이다. 공식 문서의 비유처럼 AI용 USB-C 포트에 가깝다. MCP 소개
하지만 “Slack도 보고 GitHub도 수정해”만으로는 위험하다. 필요한 서버만 연결하고, 읽기와 쓰기 권한을 나누며, 외부 전송·삭제·배포는 확인을 요구하도록 정한다.
7. 같은 실수는 감상이 아니라 규칙으로 바꾼다
AI가 두 번 같은 실수를 했다면 원인을 한 줄 규칙으로 바꾼다. 예를 들어 테스트를 빼먹었다면 AGENTS.md에 “변경한 패키지의 테스트를 실행하고 결과를 보고할 것”을 추가한다.
개발자가 바로 쓰는 Context 체크리스트
- 이번 작업의 결과물과 완료 조건이 한 문장으로 보이는가?
- 사실·링크·파일의 최신 원본과 우선순위를 지정했는가?
- 재사용할 규칙은
AGENTS.md또는CLAUDE.md로 옮겼는가? - 개인 취향, 프로젝트 규칙, 오늘의 요청을 섞지 않았는가?
- 민감 정보와 외부 쓰기 권한의 경계를 정했는가?
- 구현 전에 영향 범위와 계획을 확인했는가?
- 같은 실수를 재발 방지 규칙으로 기록했는가?
핵심 요약
좋은 Context는 AI에게 장문의 설명을 주는 일이 아니다. 변하지 않는 규칙은 파일에, 최신 사실은 원본 자료에, 이번 목표는 요청에, 위험한 행동은 승인 규칙에 둬서 AI가 같은 기준으로 판단하게 만드는 일이다. 오늘은 자주 쓰는 프로젝트 하나를 골라 AGENTS.md나 CLAUDE.md에 ‘완료 전 반드시 할 검증’ 한 줄만 추가해 보자.
다음 편에서는 이 원칙을 실제 AGENTS.md 템플릿으로 옮겨, 개인 프로젝트와 팀 프로젝트에 각각 어떻게 적용하는지 살펴보겠다.
자료 확인일: 2026년 7월 22일
OpenAI Codex Manual · Claude Code: Memory and CLAUDE.md · OpenAI: Projects in ChatGPT · OpenAI: Memory FAQ · Model Context Protocol
이전글: 프롬프트 엔지니어링은 끝났다? 컨텍스트 엔지니어링이란 무엇인가
#ContextEngineering #컨텍스트엔지니어링 #AI코딩 #Codex #ClaudeCode #ChatGPT #AGENTSmd #CLAUDEmd #MCP #프롬프트엔지니어링 #바이브코딩 #AI개발
댓글
댓글 쓰기