Development4 min read

AI에게 필요한 최소 문맥만 제공하는 절차 — 관련 파일·호출 경로·오류 고르는 방법

2026년 10월 13일4 min read

AI에 전체 코드를 붙여넣지 않고도 문제를 해결하려면 '재현 가능한 최소 재현 사례(minimal repro)'와 명확한 호출 경로·오류 요약을 준비해야 합니다. 이 글은 단계별 체크리스트와 Node.js 예제를 통해 어떤 파일을 골라야 하는지, 호출 경로를 어떻게 표시할지, 어떤 오류 정보를 포함해야 하는지 실용적으로 정리합니다.

#AI#context-minimization#debugging#reproducibility
AI에게 필요한 최소 문맥만 제공하는 절차 — 관련 파일·호출 경로·오류 고르는 방법

요약 답변: 문제를 재현하는 데 꼭 필요한 파일(에러가 난 파일과 해당 파일을 호출하는 경로들), 축약된 스택 트레이스/오류 메시지, 그리고 이를 재현하는 최소 실행 방법(명령·HTTP 요청·테스트)을 준비해 AI에 제공하면 된다.

언제/왜 이 기법이 필요한가

대형 코드베이스나 민감 정보가 섞인 저장소에서 전체 코드를 AI에 보내기 어렵거나 비효율적일 때, 문제 해결에 직접 관련된 최소 문맥만 제공하면 빠르게 원인 추론과 해결 제안을 받을 수 있습니다. 또한 토큰·시간 제약 때문에도 필수적입니다.

어떻게 작동하나: 핵심 원칙

  • 관련성: AI가 문제를 파악하는 데 직접적으로 쓰이는 정보만 포함한다.
  • 재현성: 전달한 문맥만으로 동일한 오류가 재현되어야 한다.
  • 정확한 호출 경로: 스택 프레임(파일명·라인) 또는 함수 호출 흐름을 명확히 한다.
  • 환경·명령: 어떤 버전·명령으로 실행했는지 단순히 적어 재현 가능하게 한다.

실제 절차: 관련 파일·호출 경로·오류 고르는 단계별 체크리스트

  1. 증상·입력·출력 먼저 캡처
    • 오류 메시지 원문(카피) — 전체 메시지를 붙이지 말고 핵심 문장과 첫 5~10줄의 스택만 포함.
    • 입력 데이터(요청 바디, 쿼리, 환경 변수 값 등) — 민감 정보는 마스킹하고 예시값으로 대체.
  2. 호출 경로(trace)를 좁혀라

    스택 트레이스가 있다면 상위(서비스/프레임워크) 레벨은 생략하고 애플리케이션 코드가 포함된 프레임만 남긴다. 스택이 없으면 빠른 로그 추가 또는 짧은 재현 스크립트를 만들어 호출 흐름을 캡처한다.

    예시 명령(코드 위치 찾기):

    git grep "functionName" -n
rg "functionName" -n   # ripgrep 설치된 환경
  3. 포함할 파일 선정 규칙
    1. 에러가 발생한 파일(파일명·문제 라인 포함).
    2. 그 파일을 직접 호출하거나 import/require 하는 상위 파일들(엔트리 포인트부터 에러 파일까지의 경로).
    3. 환경·설정 파일: 애플리케이션의 동작에 영향을 주는 config, .env(민감 값은 마스킹) 또는 빌드 파일(package.json, requirements.txt 등).
    4. 테스트/재현 스크립트: 문제를 최소한으로 재현하는 스크립트 한 파일(또는 단위 테스트 파일).

    의존성이 큰 라이브러리는 명세만 포함(package.json 등)하고 라이브러리 전체 코드는 포함하지 않는다.

  4. 최소 재현 사례 만들기

    원본 프로젝트에서 관련 코드와 설정만 뽑아 별도 폴더로 재구성한다. 이 단계에서 재현 여부를 확인해야 한다.

    포함 항목 요약: 파일 목록 + 복제 방법(예: git patch, 파일 텍스트 붙여넣기) + 실행 명령.

  5. 오류 아티팩트 정리
    • 축약된 스택 트레이스(관련 프레임 3~6개).
    • stderr/stdout 로그 중 타임스탬프·거대한 로그는 생략하고 문제 발생 직전·직후 10~50줄만 포함.
    • 명확한 재현 명령(또는 curl/HTTP 요청), 기대값과 실제값 비교.
  6. AI에 보낼 때의 포맷(권장)
    1. 한 줄 요약: "어떤 증상"
    2. 재현 단계(숫자 목록으로): 설치·실행·요청
    3. 포함된 파일 목록(파일명과 역할)
    4. 축약된 스택 트레이스와 관련 코드 스니펫(파일:라인 형태로)
    5. 시도해 본 것(로그 추가, 임시 수정)과 가정(예: 환경변수 A가 없어서 발생할 것으로 추정)

예제: Node.js(Express)에서 실패한 라우트의 최소 문맥 추출

문제: POST /users 호출 시 500 에러가 발생한다. 전체 서버 코드를 보내지 않고 AI에게 보낼 최소 문맥을 준비한다.

1) 캡처한 증상(요약)

요약: POST /users 호출 시 500 Internal Server Error
요청: curl -X POST http://localhost:3000/users -H 'Content-Type: application/json' -d '{"name":"Alice"}'
스택(원문 중 관련 부분):
Error: Cannot read properties of undefined (reading 'save')
    at createUser (/path/to/project/controllers/userController.js:42:15)
    at Layer.handle [as handle_request] (/path/to/project/node_modules/express/lib/router/layer.js:95:5)
    at next (/path/to/project/node_modules/express/lib/router/route.js:144:13)

2) 선택한 파일 목록

  • controllers/userController.js — 에러가 난 함수(createUser)와 문제 라인 포함
  • routes/users.js — 라우트 정의(엔드포인트가 여기서 연결됨)
  • server.js — 간단한 앱 초기화(Express 설정, 미들웨어)
  • package.json — 의존성 명세 및 실행 명령
  • repro.sh 또는 curl 명령 — 재현 방법

3) 최소 파일 예시(축약)

// server.js
const express = require('express');
const usersRouter = require('./routes/users');
const app = express();
app.use(express.json());
app.use('/users', usersRouter);
app.listen(3000);

// routes/users.js
const express = require('express');
const router = express.Router();
const { createUser } = require('../controllers/userController');
router.post('/', createUser);
module.exports = router;

// controllers/userController.js
exports.createUser = async function(req, res) {
  const userModel = req.app.get('models').User; // <-- 문제 지점 가능성
  const user = new userModel(req.body);
  await user.save();
  res.status(201).json(user);
};

재현 명령(예):

node server.js
# 다른 터미널에서
curl -X POST http://localhost:3000/users -H 'Content-Type: application/json' -d '{"name":"Alice"}'

4) AI에 보낼 요약(예)

한줄 요약: POST /users에서 userModel이 undefined여서 'save' 호출 시 에러
재현 단계:
 1. node server.js
 2. curl ... (위 명령)
포함 파일: server.js, routes/users.js, controllers/userController.js, package.json
관련 스택(축약): Error: Cannot read properties of undefined (reading 'save')
    at createUser (controllers/userController.js:3:15)
시도한 것: req.app.get('models') 값 로그 출력 -> undefined
가정: app에 models가 등록되지 않았거나 미들웨어 순서 문제
원하는 도움: 왜 req.app.get('models')가 undefined인지 가능한 원인과 검사 포인트

이 정도면 AI는 호출 경로(POST /users → routes/users.js → controllers/createUser)와 핵심 오류(Undefined 모델)에 바로 집중할 수 있다.

제한사항 및 흔한 실수

  • 과도한 코드 포함: 전체 저장소를 붙이면 핵심이 묻혀버리고 토큰 낭비가 발생한다.
  • 환경 불일치: 로컬에서만 재현되는 문제(예: 특정 DB 상태, 비동기 타이밍)는 최소 재현 사례로 만들기 어렵다. 이런 경우에는 DB 스냅샷이나 가짜(모의) 데이터를 제공하라.
  • 비결정적/경합 상태: 재현이 꾸준히 되지 않으면 AI가 원인 추론하기 어렵다. 재현 절차에 성공률(예: 1/10 실패)을 적어라.
  • 민감 정보 누출: .env나 비밀번호는 예시 값으로 대체하고 원본은 제거하라.
  • 불충분한 가정 기술: 이미 시도한 디버깅(로그 추가, 가설)과 결과를 반드시 적어야 중복 제안이 줄어든다.

마지막으로, 최소 문맥은 원인 후보를 좁히기 위한 시작점이다. AI가 제안한 수정·원인에 대해 직접 다시 검증 가능한 재현 절차를 포함하면 문제 해결 속도가 훨씬 빨라진다.

실용적 요약: 문제 증상 → 축약된 스택과 호출 경로 → 관련 파일 목록 → 최소 실행 명령 순으로 정리하여 AI에 제공하라. 이렇게 하면 불필요한 코드 없이도 빠르고 정확한 진단 제안을 받을 수 있다.