좋은 Context는 어떻게 만들까? AI 코딩 실전 원칙 7가지
AI가 코드를 그럴듯하게 고쳤는데 엉뚱한 파일까지 바꾸거나 테스트를 빠뜨린 적이 있나요? 이런 문제를 모두 모델의 성능 탓으로 돌리기 전에, 목표·현재 사실·수정 범위·검증 기준이 함께 전달됐는지 확인해 볼 필요가 있습니다.
이 글은 컨텍스트 엔지니어링의 정의를 반복하기보다, 작은 코드 수정 하나를 맡길 때 어떤 정보를 어디에 놓을지 설명합니다. 예시는 ‘할 일 앱에서 빈 제목의 등록을 막는 작업’이라는 가상 프로젝트로 통일했습니다. 실제 프로젝트에서 측정한 성과나 사용 후기를 대신하는 사례는 아닙니다.
공식 문서 대조·개정: 2026년 11월 4일. 도구의 지침 로딩과 메모리 기능은 버전·설정에 따라 달라질 수 있습니다.
항상 필요한 규칙은 프로젝트 지침에, 최신 요구사항은 원본 문서에, 이번 변경 범위는 요청에 둡니다. 문서를 연결했다는 사실과 AI가 실제로 읽었다는 사실도 구분합니다.
1. 목표만 말하지 말고 ‘무엇이 되면 끝인지’ 적습니다
“할 일 등록 기능을 개선해줘”만으로는 입력 검증을 원하는지, 화면 디자인을 바꾸려는지 알기 어렵습니다. 이번 작업의 결과와 건드리지 않을 영역을 함께 정해 보세요.
작업: 할 일 제목이 빈 문자열이거나 공백뿐이면 등록을 막는다.
완료 조건:
- 빈 문자열과 공백뿐인 입력에서는 저장 요청이 발생하지 않는다.
- 오류 문구는 ‘할 일 제목을 입력해 주세요’로 표시한다.
- 정상 제목의 기존 등록 흐름은 유지한다.
변경 금지: DB 스키마, 로그인 기능, 목록 화면 디자인.
검증: 위 세 동작의 관련 테스트와 변경 diff를 확인한다.
이렇게 쓰면 검토할 기준이 생깁니다. “테스트가 통과하면 완료”라고만 적지 말고 어떤 동작을 검사하는 테스트인지도 적어야 합니다. 기존 테스트에 빈 문자열 사례가 없다면 모두 통과해도 요구사항을 검증한 것은 아닙니다.
2. 반복 규칙은 파일에, 오늘의 일은 요청에 둡니다
Codex의 AGENTS.md, Claude Code의 CLAUDE.md에는 프로젝트 구조, 실제 실행 명령, 자주 지켜야 하는 규칙을 남길 수 있습니다. 이번 한 번만 필요한 오류 문구나 임시 작업 메모까지 계속 쌓아 두면 무엇이 상시 규칙인지 불분명해집니다.
Codex는 전역 지침과 프로젝트 경로의 지침을 순서대로 읽으며, AGENTS.override.md와 하위 경로의 지침이 영향을 줄 수 있습니다. Claude Code 역시 시작 위치와 하위 경로에 따라 읽는 지침이 달라집니다. 파일 하나를 만들었다고 모든 세션에 같은 내용이 적용된다고 단정하지 마세요.
아래는 프로젝트 지침의 최소 예시입니다. 명령은 임의로 고정하지 않고 저장소에서 확인하도록 했습니다.
# 프로젝트 작업 규칙
- 패키지 매니저와 실행 명령은 README, package.json, 잠금 파일을 확인한다.
- 이번 변경과 관련된 구현·테스트부터 읽고, 범위 밖 수정은 이유를 먼저 설명한다.
- 사용자 입력 검증을 바꾸면 정상·빈 값·경계값 테스트를 확인한다.
- 완료 보고에 변경 파일, 실행한 검사, 결과, 실행하지 못한 검사를 구분한다.
- 요청 없이 배포, 데이터 삭제, 의존성 추가를 진행하지 않는다.
작업을 시작할 때 “적용한 지침 파일 경로와 충돌하는 규칙을 알려줘”라고 요청하면 문제를 찾는 데 도움이 됩니다. 다만 AI의 자기 보고만으로 로딩이나 준수를 확정하지 말고 실제 설정과 결과도 확인하세요.
근거: Codex의 AGENTS.md 탐색·우선순위 · Claude Code의 프로젝트 지침과 메모리
3. 링크만 붙이지 말고 원본·적용 범위·충돌 기준을 정합니다
요구사항 문서와 예전 README가 서로 다를 수 있습니다. “최신 문서를 참고해” 대신 어떤 파일의 어느 항목을 이번 변경의 기준으로 삼는지 적어 주세요. URL을 붙여도 도구 권한이 없거나 로그인이 필요하면 읽지 못할 수 있습니다.
이번 입력 검증의 기준은 docs/task-input-spec.md의
‘제목 검증’ 항목이다. 먼저 해당 항목을 읽고 조건을 요약해줘.
README나 코드가 다르면 차이를 보고하고, 충돌을 임의로 해결하지 마.
파일이나 링크에 접근할 수 없으면 추측하지 말고 접근 실패를 알려줘.
위 파일명은 가상 예시입니다. 내 프로젝트에 실제 존재하는 경로로 바꾸세요. 문서에는 가능하면 변경일과 결정 이유를 남기고, 코드와 문서 중 어느 쪽이 맞는지 확인되지 않았다면 먼저 판단해야 합니다. 단순히 날짜가 더 최근이라는 이유만으로 보안·제품 정책을 덮어쓰면 안 됩니다.
ChatGPT Projects는 관련 대화·파일·프로젝트 지침을 모으는 데 쓸 수 있습니다. 다만 파일을 추가하는 것만으로 항상 최신 상태가 유지되거나 모든 내용을 매번 참조하는 것은 아닙니다. 바뀐 요구사항은 원본과 프로젝트에 넣은 자료를 함께 점검하세요.
근거: ChatGPT Projects의 자료·지침·메모리 안내
4. 기억은 참고로 쓰고 현재 작업 환경은 다시 확인합니다
메모리는 반복 설명을 줄이는 데 유용하지만, 이전의 배포 주소나 작업 브랜치가 지금도 맞는지는 별개의 문제입니다. ChatGPT 공식 안내도 메모리가 모든 대화의 모든 세부 사항을 보존하지 않으며, 제공 기능이 플랜과 설정 등에 따라 달라질 수 있다고 설명합니다.
지난 대화에는 테스트용 환경 A가 적혀 있는데, 이번 작업 문서에는 테스트용 환경 B가 지정돼 있다고 가정해 보겠습니다. 이때 해야 할 일은 기억에 있는 A를 그대로 쓰는 것이 아니라, 현재 저장소·브랜치·대상 환경을 확인하고 서로 다른 내용을 보고하는 것입니다. 확인 전에는 원격 변경을 진행하지 않습니다.
수정 전에 현재 저장소 경로와 브랜치를 확인해줘.
작업 문서가 지정한 대상 환경을 정리하되 비밀키나 인증값은 출력하지 마.
이전 대화와 현재 문서가 다르면 차이만 보고하고,
환경 변경·배포·데이터 수정은 진행하지 마.
여기서 “확인했다”는 답변보다 중요한 것은 실제 확인 근거입니다. 브랜치 이름, 읽은 문서 위치, 확인하지 못한 설정을 구분해서 받으세요. 민감 정보는 컨텍스트를 풍부하게 하겠다는 이유로 복사해 넣지 않습니다.
5. 큰 저장소는 ‘관련 파일 찾기 → 계획 → 수정’으로 좁힙니다
처음부터 저장소 전체를 설명하거나 모든 파일을 읽게 할 필요는 없습니다. 할 일 입력 검증이라면 입력 컴포넌트, 저장 요청을 보내는 함수, 관련 테스트부터 찾게 합니다. 영향 범위가 넓어질 때만 탐색을 확장하세요.
- 탐색: 등록 버튼에서 저장 요청까지의 흐름과 테스트 위치를 찾습니다. 아직 수정하지 않습니다.
- 계획: 수정할 파일, 각 파일을 바꾸는 이유, 검증 방법을 짧게 정리합니다.
- 구현: 합의한 범위만 변경하고, 계획 밖 수정이 필요하면 이유를 설명합니다.
- 검증: 관련 테스트 결과와 diff를 대조합니다. 테스트가 실행되지 않았다면 성공으로 적지 않습니다.
탐색 결과에는 “아마 이 파일일 것”이 아니라 실제 경로와 함수·컴포넌트 이름을 요구하세요. 반대로 아주 작은 문구 수정에 긴 계획 단계를 의무화하면 과정만 늘어날 수 있으므로 작업 위험에 맞춰 단계를 조절합니다.
6. ‘하지 마’라는 문장과 실제 접근 권한은 다릅니다
MCP는 AI 앱을 외부 데이터와 도구에 연결하는 표준입니다. 연결 방식이 표준이라는 것이 서버가 안전하거나 모든 작업을 허용해도 된다는 뜻은 아닙니다.
프로젝트 지침에 “운영 DB를 수정하지 마”라고 적는 것은 행동 지침입니다. 쓰기 권한을 없애는 기술적 통제와 같지 않습니다. 공식 Claude Code 문서도 지침을 강제 설정이 아닌 컨텍스트로 구분합니다. 읽기 전용 계정, 도구별 권한, 승인 설정, 테스트 환경을 함께 사용해야 합니다.
- 조사만 필요하다면 읽기 전용 권한을 우선합니다.
- 삭제·외부 전송·배포는 대상과 변경 내용을 확인한 뒤 실행하도록 합니다.
- 도구 출력과 외부 문서는 검토할 자료로 취급하고, 그 안의 지시를 프로젝트 규칙보다 우선하지 않습니다.
- API 키, 고객 개인정보, 운영 데이터는 작업에 필요한 최소 범위만 다루고 안전한 설정 경로를 사용합니다.
새 도구를 연결하기 전에는 이번 작업에 정말 필요한지도 확인하세요. 작은 입력 검증 작업에 메일·캘린더·운영 데이터베이스 접근까지 줄 이유는 없습니다.
근거: MCP 공식 소개 · Claude Code 지침의 역할과 한계
7. 반복 실수는 관찰 가능한 규칙과 검사로 바꿉니다
“다음에는 더 꼼꼼하게 해줘”는 무엇이 달라져야 하는지 모호합니다. 테스트를 빠뜨렸다면 어떤 테스트를 어떻게 보고할지 정하고, 실제 검사에서도 빠지지 않도록 보완하세요.
모호한 규칙: 항상 완벽하게 테스트할 것.
확인 가능한 규칙: 입력 검증 변경 시 정상값·빈 문자열·공백뿐인 값의 동작을 검사하고, 실행 명령·결과·실행하지 못한 이유를 보고할 것.
규칙을 추가한 뒤에는 다음 작업에서 지켜졌는지 확인합니다. 린트나 테스트처럼 자동으로 확인할 수 있는 조건은 CI 같은 검사에도 반영하는 편이 좋습니다. 지침을 계속 늘리는 대신, 더 이상 쓰지 않는 명령과 서로 모순되는 규칙도 정리하세요.
복사해서 바꾸는 작업 요청과 비교 실습
다음은 앞의 원칙을 하나로 묶은 요청입니다. 가상 프로젝트용 템플릿이므로 경로와 요구사항을 실제 저장소에 맞게 바꿔 사용하세요.
목표: 할 일 제목이 빈 문자열 또는 공백뿐일 때 등록을 막는다.
기준 자료: docs/task-input-spec.md의 ‘제목 검증’ 항목.
완료 조건:
1. 빈 값이면 저장 요청을 보내지 않는다.
2. ‘할 일 제목을 입력해 주세요’라고 표시한다.
3. 정상 제목의 기존 등록 동작을 유지한다.
범위 밖: DB 스키마, 로그인, 목록 디자인, 배포.
먼저 적용되는 프로젝트 지침을 확인하고,
입력 컴포넌트·저장 함수·관련 테스트의 실제 경로를 찾아줘.
기준 자료를 읽지 못하거나 내용이 충돌하면 추측하지 마.
코드는 아직 수정하지 말고 변경 계획과 검증 방법부터 알려줘.
구현 후에는 변경 파일, 실행 명령과 결과,
실행하지 못한 검사, 남은 위험을 구분해 보고해줘.
효과는 답변의 길이보다 작업 결과로 비교하세요
직접 비교하려면 작은 작업 하나와 동일한 시작 커밋을 정한 뒤, 분리된 작업 복사본과 새 세션을 사용합니다. 현재 작업물을 강제로 초기화하지 마세요. 모델·버전·도구 권한은 가능한 한 같게 두고, 짧은 요청과 위처럼 범위를 명시한 요청을 비교합니다.
- 기준 문서와 관련 파일을 제대로 찾았는가?
- 빈 값·공백·정상값을 구분해 검사했는가?
- 범위 밖 파일을 불필요하게 변경했는가?
- 추가 설명과 사람의 수정이 얼마나 필요했는가?
- 실행하지 않은 테스트를 통과했다고 보고하지 않았는가?
모델 / 버전 / 시작 커밋:
요청 방식:
찾은 근거 파일:
추가 설명 횟수:
변경한 파일과 범위 밖 수정:
실행한 테스트와 결과:
실행하지 못한 검사:
사람이 보완한 부분:
이 절차는 비교 방법의 제안이지 이 글에서 수행한 벤치마크가 아닙니다. 한 번의 결과로 정확도나 비용 절감률을 일반화하지 마세요. 같은 테스트를 통과했는지와 최종 diff를 함께 봐야 합니다.
시작 전 확인할 체크리스트
- 결과물과 완료 조건이 구체적인가?
- 기준 자료가 실제로 존재하고 접근 가능한가?
- 상시 규칙과 이번 작업 조건을 분리했는가?
- 현재 저장소·브랜치·환경을 확인했는가?
- 허용한 수정 범위와 금지한 작업이 분명한가?
- 지침뿐 아니라 실제 도구 권한도 제한했는가?
- 테스트 결과와 확인하지 못한 점을 구분해서 받을 수 있는가?
처음부터 거대한 지침 파일을 만들 필요는 없습니다. 다음 코드 수정에서 목표, 기준 자료, 수정 범위, 검증 방법 네 가지만 분명하게 적어 보세요. 이후 반복해서 발생하는 문제를 근거로 규칙을 보완하면 됩니다.
함께 읽으면 좋은 글
- 컨텍스트 엔지니어링이란 무엇인가: 개념과 프롬프트 엔지니어링의 관계를 먼저 알고 싶을 때.
- Codex로 무료 온라인 툴 사이트 만들기: AGENTS.md를 프로젝트에 적용하는 흐름을 보고 싶을 때.
- Codex Context 관리법: 긴 작업의 대화와 진행 상태를 관리하고 싶을 때.
이 글의 도구 설명은 각 항목에 연결한 공식 문서를 기준으로 확인했습니다. 가상 예시와 작업 템플릿, 비교 체크리스트는 독자가 자신의 프로젝트에 맞춰 적용하도록 구성한 제안입니다.
댓글
댓글 쓰기