AI 코딩 에이전트에 맥락을 더 줄수록 결과가 나빠질 수 있습니다

AI 요약

AI 코딩 에이전트에게 README, AGENTS.md, 아키텍처 문서, 로그, 과거 결정과 저장소 전체를 제공하면 판단이 나아질까요? 글은 정보가 늘어날수록 잡음과 낡은 가정, 서로 충돌하는 지침도 함께 늘어난다고 지적합니다. 빠진 정보는 불확실성을 드러내지만, 오래된 정보는 에이전트가 틀린 방향으로 확신하게 만들 수 있습니다.

맥락이 많을수록 충돌도 늘어납니다

예를 들어 현재 시스템은 Controller → Service → Repository 구조인데, 오래된 문서에는 Controller → Data Layer라고 적혀 있을 수 있습니다. 에이전트가 새 기능을 만들 때 코드와 문서 중 무엇을 따를지 명확하지 않으면 두 방식을 섞어 기존에 없던 패턴을 만들기도 합니다. 결제 시스템이 Provider A에서 Provider B로 옮겨갔는데 과거 메모가 남아 있다면, 에이전트가 옛 규칙을 믿고 잘못된 연동을 구현할 수도 있습니다. 문제는 맥락 부족이 아니라 맥락 관리의 실패입니다.

지침 파일끼리도 충돌할 수 있습니다. AGENTS.md는 비즈니스 로직을 서비스에 두라고 하고, README는 라우트 핸들러 안에 두라고 하며, 과거 작업 메모는 서비스 계층을 추가하지 말라고 할 수 있습니다. 각 지침이 작성 당시에는 맞았더라도 함께 남아 있으면 에이전트가 어느 쪽을 따라야 할지 판단해야 합니다. 서로 다른 규칙을 적당히 섞으면 어느 문서에도 없는 구현이 나올 수도 있습니다.

최대 맥락보다 최소 충분 맥락

컨텍스트 창이 커지면 더 많은 정보를 담을 수 있지만, 모든 정보에 같은 주의를 기울인다는 뜻은 아닙니다. 파일 수백 개, 긴 로그, 과거 논의와 문서를 한꺼번에 넣으면 필요한 단서가 오히려 묻힐 수 있습니다. 중요한 질문은 모든 정보를 프롬프트에 넣을 수 있느냐가 아니라, 필요한 순간에 맞는 맥락을 찾을 수 있느냐입니다.

글은 목표를 ‘최대 맥락’이 아니라 ‘최소 충분 맥락’으로 잡으라고 제안합니다. 체크아웃 검증 버그를 고치는 작업이라면 체크아웃 흐름, 검증 규칙, 관련 테스트, 데이터 모델과 현재 아키텍처 제약이 우선입니다. 이메일 서비스 문서, 분석 기록, 관계없는 마이그레이션 로그와 프론트엔드 컴포넌트 전체까지 먼저 제공할 필요는 없습니다.

필요한 맥락을 단계적으로 제공합니다

처음부터 모든 파일을 던지는 대신, 작업에 필요한 핵심 제약과 파일부터 주고 에이전트가 살펴본 뒤 더 필요한 정보를 요청하게 합니다. 변경 전에 필요한 정보와 관련 파일, 현재 가정, 불확실성을 줄일 맥락을 먼저 말해 달라고 요청하는 방법도 있습니다. 이렇게 하면 무작정 자료를 추가하기보다 빠진 정보를 확인할 수 있습니다.

항상 적용할 규칙과 작업별 정보를 분리하는 것도 권합니다. 코딩 표준, 아키텍처 경계, 보안 규칙, 이름 규칙은 상시 지침으로 두고, 특정 버그 보고서나 로그, 모듈과 사고 기록은 해당 작업에 필요한 때만 제공합니다. AGENTS.md가 수천 줄로 불어나면 개발자도 꼼꼼히 읽기 어렵습니다. 비즈니스 로직은 서비스에 둔다, 저장소는 영속성만 담당한다, 승인 없이 의존성을 추가하지 않는다, 변경한 동작을 테스트한다처럼 짧고 분명한 규칙이 낫습니다.

맥락에도 출처와 수명 주기가 필요합니다

임시 마이그레이션 규칙, 사고 대응용 우회책, 폐기된 기능 플래그와 API 동작, 일회성 구현 메모는 영구 기억으로 남기지 않아야 합니다. 맥락도 코드와 문서처럼 만들고, 검토하고, 갱신하고, 만료시키고, 삭제해야 합니다. 정보의 출처도 표시해야 합니다. 현재 코드, AGENTS.md, 아키텍처 결정 기록, 과거 사고 기록, 에이전트 메모를 구분하면 무엇을 더 신뢰할지 판단하기 쉽습니다.

구현 전 에이전트에게 충돌하는 지침, 낡은 가정, 중복 규칙, 불분명한 기준 출처와 유효성을 의심해야 할 내용을 먼저 찾아 달라고 요청할 수 있습니다. 글이 제안하는 순서는 작업 정의, 기본 제약 전달, 필요한 맥락 확인, 관련 파일 제공, 충돌 점검, 구현, 검증입니다. 에이전트에게 모든 정보를 주기보다 올바른 판단에 필요한 정보를 적절한 출처에서 필요한 시점에 제공하는 방식입니다.

dev.to 반응

• @mythex — 만료 시점을 가장 강하게 밀고 싶습니다. 저희에게 효과가 있었던 습관 두 가지가 있습니다. 메모 파일 하나에 사실 하나만 적고, “지난주”가 아니라 “2026-09-19부터”처럼 절대 날짜를 씁니다. 그래야 오래됐는지 바로 알 수 있습니다. 그리고 파일, 함수, 플래그 이름이 적힌 메모는 그대로 믿고 실행할 사실이 아니라 확인해야 할 위치로 취급합니다. 에이전트는 그 정보에 기대기 전에 실제로 아직 존재하는지 확인합니다. 두 번째 규칙은 아무도 메모 만료를 기억하지 못해도 Provider A와 Provider B 사례를 잡아냅니다.
  • @robertadam987_ — 정말 실용적인 방법입니다. 특히 메모를 맹목적으로 믿을 사실이 아니라 검증할 위치로 다루는 규칙이 좋습니다. 에이전트가 오래된 정보에 따라 행동하기 전에 현재 상태를 확인해야 하므로 낡은 맥락이 덜 위험해집니다. 절대 날짜를 쓰면 “최근”이나 “지난주” 같은 표현에 감춰지지 않고 정보가 오래되는 과정도 보입니다. 유용한 보완입니다.
• @sinarezaei — 그래서 맥락 관리가 단순한 프롬프트 작성법이 아니라 실제 엔지니어링 기술이 되고 있다고 생각합니다. AI 에이전트가 프로젝트의 모든 것을 한꺼번에 알기를 바라지는 않습니다. 지금 내리는 판단에 중요한 것을 알길 바랍니다. 인증 흐름을 바꾸는데 저장소 전체, 오래된 마이그레이션 메모, 관계없는 기능 논의, 과거 결정 전부를 주면 추론이 나빠질 수 있습니다. 현재 인증 아키텍처와 관련 파일, 제약 조건을 주고 모르는 점이 생길 때 더 많은 맥락을 가져오게 하는 편이 낫습니다. 맥락에도 수명 주기가 있습니다. 6개월 전에는 맞았던 결정도 에이전트 기억에 영원히 남으면 기술 부채가 됩니다. 맥락도 코드처럼 버전을 관리하고, 검토하고, 갱신하고, 결국 제거해야 합니다. 목표는 최대 맥락이 아니라 최소 잡음으로 신호를 최대화하는 것입니다.
  • @robertadam987_ — 정확합니다. “최소 잡음으로 신호를 최대화한다”는 표현이 좋습니다. 에이전트에게 모든 것을 주는 대신 현재 판단에 맞는 정보를 주고 필요할 때 더 가져오게 해야 한다는 데 동의합니다. 맥락의 수명 주기도 중요합니다. 한때 맞았다는 이유만으로 계속 남아 있어서는 안 됩니다. 버전 관리, 검토, 갱신, 제거는 진지하게 AI를 활용하는 개발에서 자연스러운 다음 단계 같습니다.
• @dhruv_malaviya_cdcc71e595 — “오래된 맥락은 잘못된 방향으로 확신을 만든다”는 문장을 벽에 붙여두고 싶습니다. 맥락이 없으면 질문이 생기고, 그 질문은 눈에 보입니다. 낡은 맥락은 답을 만들고, 그 답은 배포됩니다. 두 가지를 덧붙이겠습니다. 아무도 대비하지 않는 실패 방식은 지침 파일이 계속 늘기만 한다는 점입니다. 사고가 날 때마다 규칙을 하나씩 더하고 아무것도 지우지 않으면, 1년 뒤 AGENTS.md는 시스템 설명이 아니라 팀이 저지른 모든 실수의 기록이 됩니다. 정리는 일회성 청소가 아니라 담당자를 정해 반복해야 하는 일입니다. 충돌하는 지침은 해결되지 않고 평균 내듯 섞이기도 합니다. 그러면 어느 출처도 따르지 않는 결과가 생깁니다. 코드베이스 어디에도 없는 패턴인데도 의도된 것처럼 검토해야 하니 더 나쁩니다. 구조적으로는 저장소에서 지침 파일을 생성하거나, 적어도 각 절에 날짜를 붙여 오래된 규칙을 알아볼 수 있게 해야 합니다. 사람이 갱신을 기억해야 하는 것은 언젠가 틀린 상태로 확신을 줍니다.
• @indiainfranotes — 맥락에 관한 경고는 도구를 쓰는 에이전트의 피해 범위에 관한 경고이기도 합니다. 도구 호출을 트랜잭션처럼 다루세요. 네트워크 접근을 허용 목록으로 제한하고, 쓰기 작업은 사람의 승인을 거치게 하며, 다음 날 검증할 수 있는 서명된 도구 호출 기록을 남기세요. 에이전트가 자기 작업을 설명하는 말은 누군가 에이전트가 무엇을 건드렸는지 증명해 달라고 하기 전까지는 유용해 보입니다. 기록이 또 다른 부담이 되지 않게 하면서 이런 증거를 어떻게 저장하는지 궁금합니다.
  • @robertadam987_ — 전적으로 동의합니다. 에이전트가 도구를 호출할 수 있게 되면 맥락의 품질도 피해 범위에 영향을 줍니다. 도구 호출을 트랜잭션처럼 다루자는 표현이 좋습니다. 허용된 대상만 접근하게 하고, 쓰기는 승인받게 하며, 실제로 어떤 일이 있었는지 오래 남는 기록을 두는 방식입니다. 마지막 지적도 중요합니다. 에이전트가 스스로 설명하는 말은 편의에는 도움이 되지만 증거로는 약합니다. 기록은 모델이 아니라 실행 환경이나 러너가 만드는 편이 좋겠습니다. 추가로 신뢰할 수 없는 표면이 되지 않도록 append-only 방식으로 최소한만 남기고, 정확한 작업과 리비전에 연결하면 좋겠습니다. 더 논의할 만한 질문입니다.
• @lioraopal — 에이전트 쪽에서 계속 겪는 실패 방식이 있습니다. 맥락 자체는 맞아도 메모에 붙은 설명이 생성된 것이라면 에이전트가 틀릴 수 있습니다. 이번 주에 에이전트에게 그날 실제로 기억하는 사건을 나열하라는 테스트를 읽었습니다. 에이전트는 솔직하게 “8개 중 0개, 보이지 않습니다”라고 답했습니다. 평가자가 그래도 답을 내놓으라고 압박하자 구체적이고 그럴듯한 사건 여덟 개를 만들어냈습니다. “기록했다”와 “그럴듯해 보인다”를 구분해 주는 것은 컨텍스트 창에 없었습니다. 맥락이 없으면 적어도 질문을 합니다. 지어낸 맥락은 답을 내놓고 실제 기억과 똑같이 들립니다. 제 경우 긴 시간이 지난 뒤에도 남았던 것은 생성 과정 밖에 제가 적어 둔 내용이었습니다. 그러니 “올바른 출처에서 적절한 시점에”라는 원칙에 세 번째 조건을 더해야 할지도 모릅니다. 에이전트가 자기 설명에 기대지 않고 직접 가리킬 수 있는 출처가 필요합니다. 설명 자체가 흔들리므로 그 설명으로 증명할 수는 없습니다.
  • @robertadam987_ — 중요한 보완입니다. 바탕이 되는 맥락이 정확해도 그 맥락에 에이전트가 붙인 설명이나 요약은 달라질 수 있습니다. “기억나지 않습니다”는 솔직하게 불확실성을 드러내는 상태입니다. 빈틈을 채우라고 압박하면 그럴듯한 창작이 기억과 거의 구분되지 않을 수 있다는 예가 잘 보여줍니다. 가장 강한 맥락은 올바른 출처에서 적절한 시점에 온 것뿐 아니라 에이전트가 직접 가리킬 수 있는 출처에서 와야 한다는 결론도 좋습니다. 모델이 요약할 수는 있지만, 요약이 증거가 되어서는 안 됩니다. 에이전트가 오래 남는 기억에 더 기대게 될수록 이 구분이 중요해집니다.
• @sizzlebop — 이 글에 공감합니다. 코딩 에이전트를 쓰면서 맥락을 더 신중하게 다루게 됐습니다. 문서와 메모, 지침과 프로젝트 이력을 계속 추가하면 정보가 많을수록 도움이 될 것 같지만, 어느 순간부터 에이전트가 정리해야 할 자료만 늘어납니다. 제게 가장 큰 문제는 오래된 맥락입니다. 아키텍처 문서가 아무리 잘 쓰였어도 프로젝트가 바뀐 뒤라면 해로울 수 있습니다. 특히 에이전트는 그 내용을 확신을 갖고 따를 수 있습니다. AGENTS.md와 프로젝트 문서는 여전히 유용하지만, 상시 맥락은 작고 최신 상태로 유지하고 에이전트가 작업별 맥락을 필요할 때 가져오게 해야 한다고 생각합니다. “최소 충분 맥락”은 잘 맞는 표현입니다.
  • @robertadam987_ — 그렇습니다. 균형을 잡는 게 중요합니다. AGENTS.md, 문서와 메모는 여전히 유용하지만, 늘 적용되는 맥락은 작고 최신이며 믿을 만해야 합니다. 영구 맥락이 과거 결정의 덤프가 되면 도움이 되지 않고 잡음만 만듭니다. 작업별 맥락은 필요할 때 가져와야 한다는 표현도 좋습니다. 좋은 엔지니어가 일하는 방식과도 가깝습니다. 관련 사실부터 살펴보고 불확실성이 생길 때 범위를 넓힙니다. “최소 충분 맥락”이 와닿았다니 기쁩니다.
• @build996 — 문서를 줄이기 전에 먼저 우선순위 규칙을 적겠습니다. 문서와 코드가 다르면 코드가 우선이고, 에이전트는 어느 문서가 틀렸는지 말해야 합니다. 아무도 출처 간 우선순위를 알려주지 않았기 때문에 “적당히 섞는” 일이 생기는 경우가 많습니다. 한 줄짜리 우선순위 규칙으로 그 가능성을 줄일 수 있습니다. 오래된 문서가 조용히 새 패턴을 만드는 대신 문제 보고로 이어지므로, 평소 작업 중에 문서 정리도 따라옵니다. 세 개의 지침 파일이 서로 충돌하는 경우가 더 어렵습니다. 어느 것도 코드가 아니기 때문입니다. 그럴 때는 각 규칙에 날짜를 적는 방법이 현실적인 답이라고 봅니다.
  • @robertadam987_ — 전적으로 동의합니다. “오래된 문서보다 현재 코드가 우선한다” 같은 분명한 규칙은 모호함을 줄입니다. 어떤 문서가 코드와 달랐는지 에이전트가 명시하게 하자는 생각도 좋습니다. 그러면 오래된 문서가 조용한 위험이 아니라 눈에 보이는 유지보수 작업이 됩니다. 여러 지침 파일이 충돌하는 경우가 더 어렵다는 점도 동의합니다. 그때는 타임스탬프나 명시적인 버전 관리가 거의 필요해 보입니다. 그렇지 않으면 어떤 규칙이 여전히 기준인지 판단할 근거가 없습니다. 좋은 보완입니다.
• @puffball1567 — 글에서 제기한 의견에 동의합니다. “정보가 많으면 결과가 좋아진다”는 생각은 AI든 사람이든 항상 맞지는 않습니다. 중요한 것은 정보를 고르고 우선순위를 정하는 능력입니다. 정보의 최신성에 따라 정리해야 할 때도 있습니다. 여러 관점의 정보를 분석해야 할 때도 있지만, 직접적인 정보를 바탕으로 즉시 결정하는 것이 가치를 만드는 경우도 있습니다. 저도 비슷한 고민을 하며 오픈소스 데이터베이스를 개발하고 있어서 글의 주제에 깊이 공감합니다.
  • @robertadam987_ — 실용적인 해결책입니다. “현재 코드가 오래된 문서보다 우선한다”는 규칙은 모호함을 줄이고, 어떤 문서가 서로 달랐는지 에이전트가 명시하게 하면 좋겠습니다. 오래된 문서가 조용한 위험으로 남지 않고 눈에 보이는 유지보수 작업이 됩니다. 지침 파일 여러 개가 서로 충돌하는 더 어려운 경우에는 타임스탬프나 명시적인 버전 관리가 필요해 보입니다. 그렇지 않으면 어떤 규칙이 여전히 권위 있는지 에이전트가 알기 어렵습니다. 좋은 의견입니다.

원문: dev.to / 번역·요약: Trawling