검색 결과가 오래된 글을 먼저 보여준다고 가정하자. 코딩 에이전트에게 수정해달라고 요청했더니 제목 비교 코드를 바꿨다. 정렬은 그대로다. 이때 “모델이 코딩을 못한다”라고만 기록하면 다음 시도도 비슷한 프롬프트를 반복하기 쉽다. 실제로는 요구사항을 잘못 읽었는지, 정렬 함수를 못 찾았는지, 수정한 파일을 실행 환경에 반영하지 못했는지부터 구분해야 한다.
Matt Pocock의 AI Coding Dictionary는 모델, 문맥, 도구, 작업 패턴을 구분하는 데 참고할 만한 원자료다. 이 글은 사전 전체를 번역하지 않고 자주 섞이는 개념을 가상의 검색 기능 수정 작업에 연결했다. 아래 파일명과 테스트는 설명용 예시이며 이 블로그에서 발생한 실제 장애 기록은 아니다. 특정 제품의 UI나 기능 이름은 버전에 따라 다를 수 있다.
1. 모델·파라미터·추론: 답을 만드는 부분을 구분한다
모델은 학습한 파라미터와 계산 구조를 이용해 입력에서 출력을 생성한다. 대화형 제품에는 검색, 메모리, 코드 실행 같은 기능도 있지만 그 전체를 모델 하나와 같은 뜻으로 쓰면 원인을 놓친다. 생성 모델이 제안한 수정과 실행 도구가 적용한 수정은 서로 다른 단계다. 답변에 “수정했다”라고 적혀 있어도 파일의 변경 내역이 없으면 적용을 확인한 것이 아니다.
파라미터는 학습 과정에서 조정한 값이다. 일반적인 대화에서 정정 문장을 한 번 보내는 행위와 파인튜닝은 다르다. 서비스가 대화를 메모리에 저장하거나 다음 요청에 다시 붙이면 정정 사항을 반영할 수 있지만, 그 사실만으로 기반 모델의 가중치를 갱신했다고 볼 수 없다. “어제 알려줬는데 오늘 기억하지 못한다”는 문제에서는 저장 여부와 재주입 경로를 먼저 살핀다.
다음 토큰 예측은 생성형 언어 모델을 설명하는 기본 원리지만 오류의 원인을 전부 설명하지는 못한다. 훈련 데이터의 한계, 질문의 모호함, 검색 실패, 도구 오류가 함께 작용할 수 있다. 모델이 제시한 함수명이 없으면 공식 API 문서와 설치 버전을 확인한다. 존재하지 않는 함수를 다시 시도하라고 압박해도 실행 환경은 바뀌지 않는다.
추론 effort나 thinking budget이라는 설정은 제품이 모델의 추론 자원을 조절하도록 제공하는 제어 항목이다. 지원 값과 과금 방식은 제공자마다 다르므로 Low·High·Max 같은 이름을 공통 규격으로 외우지 않는다. 같은 수정에서 옵션을 비교하려면 입력, 테스트, 실행 환경을 고정하고 성공 여부와 소요 자원을 함께 기록해야 한다. 높은 설정을 사용했다는 사실만으로 검수 단계를 생략하지 않는다.
비결정성은 같은 요청에서도 출력이 달라질 수 있다는 성질이다. 샘플링 설정뿐 아니라 실행 환경과 모델 버전의 변화도 확인해야 한다. 다시 시도하는 전략은 가능하지만 성공한 한 번만 평가에 남기면 안정성을 과장한다. 지식 기준일 역시 서비스 전체의 최신 정보 접근 여부와 같지 않다. 모델 학습에서 얻은 지식, 사용자가 준 자료, 검색 도구가 가져온 최신 문서를 구분하고 현재 API 명세는 공식 문서에서 확인한다.
2. 토큰·컨텍스트: 에이전트가 받은 자료를 확인한다
토큰은 텍스트를 모델이 처리할 단위로 나눈 조각이다. 언어와 토크나이저에 따라 단어 하나가 여러 조각이 될 수 있다. 한글 글자 수에 고정 비율을 곱해 비용이나 남은 문맥을 정확히 계산하려고 하지 않는다. 제품이 제공하는 실제 사용량과 토큰 계산 방법을 확인해야 한다.
컨텍스트는 현재 모델 호출에 제공한 입력이다. 지시문, 이전 대화, 도구 설명, 읽은 파일, 실행 결과 등이 포함될 수 있다. 컨텍스트 윈도우는 처리 가능한 범위이지 모든 정보를 같은 정확도로 활용한다는 보증이 아니다. 검색 정렬을 고치는데 화면 스타일 파일만 읽혔다면 긴 문맥보다 관련 코드의 부재가 먼저 문제다.
작업 자료는 질문과의 관계로 고른다. 정렬 요구사항, 날짜를 파싱하는 함수, 목록을 만드는 함수, 실패를 재현하는 입력을 우선 전달한다. 전체 저장소를 한 번에 붙이는 방식과 필요한 파일을 찾아 읽는 방식의 비용·정확도는 작업별로 비교한다. 원본 파일의 경로와 커밋도 함께 남기면 오래된 복사본을 참조했는지 확인할 수 있다.
주의력 저하나 smart zone은 긴 문맥에서 정보 활용이 달라지는 현상을 설명할 때 쓰는 표현이다. 모든 모델에 적용되는 “문맥의 몇 퍼센트까지 안전하다”는 공통 경계로 받아들이면 곤란하다. Lost in the Middle 연구는 평가한 모델과 과제에서 정보 위치에 따른 성능 차이를 보고했다. 현재 사용하는 모델의 코드 작업도 같은 폭으로 저하된다고 단정하지 말고 자신의 과제로 확인한다.
3. 도구·MCP·샌드박스: 읽기와 실행의 권한을 나눈다
도구 호출은 모델이 요청한 구조화된 작업을 실행 시스템이 처리하는 과정이다. 파일 읽기, 터미널 실행, 검색 API 호출은 도구의 예다. 도구를 정의했다고 호출이 성공하는 것은 아니다. 인자의 형식, 실행 권한, 연결 상태, 실제 반환값까지 확인해야 한다.
MCP는 AI 애플리케이션과 외부 데이터·기능을 연결하는 표준이다. 공식 설명에는 도구뿐 아니라 자료와 프롬프트 같은 구성 요소도 나온다. MCP 서버를 연결했다는 사실과 그 서버에 어떤 권한을 줬는지는 별도 항목이다. 읽기 전용 이슈 조회와 이슈 삭제를 같은 연결 이름 아래 제공할 수도 있으므로 허용 기능을 살핀다. MCP 공식 소개
샌드박스는 실행 환경의 접근 범위를 제한하는 장치다. 승인 요청은 특정 동작을 사람이 허용할지 결정하는 절차다. 둘은 함께 사용할 수 있지만 같은 기능은 아니다. 네트워크를 막은 샌드박스에서 문서 검색이 실패했다고 모델을 바꿀 이유는 없다. 반대로 파일 접근을 허용했다고 외부 업로드까지 허용했다고 해석해서도 안 된다.
가상 검색 수정 작업에서는 저장소 파일 읽기와 로컬 테스트를 허용하고 운영 DB 삭제나 배포는 별도 승인으로 묶을 수 있다. 도구 결과에 민감한 값이 들어오는지도 확인한다. 오류를 조사하려고 환경 변수 전체를 출력하면 문제를 찾기 전에 비밀정보를 로그에 남길 수 있다.
4. 하네스·에이전트·워크플로: 작업을 이어가는 규칙
하네스는 모델 호출 주변에서 도구, 문맥, 반복 실행, 검증을 관리하는 실행 장치를 가리킬 때 쓰인다. 제품마다 포함하는 범위가 다르므로 “우리 하네스가 무엇을 책임지는가”를 문서에 적는 편이 낫다. 재시도 횟수, 테스트 실패 처리, 승인 경계, 종료 조건이 이 범위에 들어간다면 구현 위치도 연결한다.
에이전트는 환경에서 얻은 결과를 바탕으로 다음 행동을 선택하는 시스템이라는 뜻으로 자주 쓰인다. 워크플로는 정해진 절차를 따라 여러 단계를 수행한다. Anthropic은 두 접근을 구분하면서 필요한 경우에만 복잡도를 늘리라고 설명한다. 모든 자동화에 여러 에이전트가 필요한 것은 아니다. Building effective agents
검색 날짜 정렬 수정은 요구사항 확인, 실패 재현, 코드 수정, 검사라는 절차로 충분할 수 있다. 파일 위치를 모르면 탐색을 추가하되 끝없이 코드를 바꾸지 않도록 중단 조건을 둔다. 같은 테스트가 두 번 실패하면 실패 메시지와 현재 가설을 정리하고 원인을 다시 조사하는 식이다. 재시도 횟수는 이 예제의 운영 선택이며 범용 정답이 아니다.
서브에이전트는 분리된 작업을 다른 에이전트에 맡기는 방식이다. 독립적으로 읽을 수 있는 문서 검증에는 유용할 수 있지만 두 에이전트가 같은 함수를 동시에 바꾸면 충돌한다. 위임할 때 파일 범위, 입력, 반환할 결과, 수정 가능 여부를 명시한다. 인원을 늘리는 일과 검증 책임을 분명히 하는 일은 별개다.
5. 압축·핸드오프·메모리: 다음 세션이 이어받을 것
압축은 긴 대화의 일부를 요약하거나 다른 형태로 줄여 문맥을 관리하는 방법이다. 실제로 어떤 내용을 보존하고 다시 가져올 수 있는지는 제품에 따라 다르다. “압축하면 원본은 무조건 사라진다”라고 단정하지 않는다. 중요한 명령, 실패 로그, 사용자 결정은 별도 파일이나 작업 기록에 연결해두면 재확인이 쉽다.
핸드오프는 다른 세션이나 담당자가 작업을 이어받도록 현재 상태를 전달하는 일이다. 길게 설명한 대화보다 지금 무엇이 바뀌었고 무엇이 남았는지 찾을 수 있어야 한다. 아래는 가상 작업의 인수인계 양식이다. 실행하지 않은 검사에는 성공 표시를 넣지 않는다.
| 기록 항목 | 예시 |
|---|---|
| 목표 | 최신 작성일 순으로 글 목록 정렬 |
| 수정 범위 | 예시 경로 src/posts/sort.ts |
| 원자료 | 요구사항 문서와 재현 입력의 경로 |
| 확인한 결과 | 실행한 명령·종료 코드·검사 시각 |
| 남은 문제 | 날짜가 없는 글의 배치 순서 결정 필요 |
| 금지한 작업 | 운영 DB 변경과 사용자 승인 없는 배포 |
메모리는 다음 요청에 다시 활용할 정보를 저장하는 시스템이다. 파일이 있다고 자동으로 읽히지는 않는다. 읽는 시점과 적용 범위, 오래된 정보의 갱신 방법을 확인한다. 이전 결정과 새 지시가 충돌하면 무엇을 우선할지도 필요하다. 블로그 발행 규칙처럼 코드와 연결된 지침은 현재 실행 코드와 함께 검토해야 한다.
6. AGENTS.md·스킬·점진적 공개: 문서를 실행에 연결한다
AGENTS.md는 여러 코딩 도구에서 프로젝트 지침을 제공하는 데 사용하는 파일명이다. 모든 에이전트가 같은 탐색 규칙으로 읽는다고 가정하지 않는다. 사용하는 도구의 지침 범위와 우선순위를 확인한다. 문서에는 프로젝트 전체 설명을 반복하기보다 검사 명령, 변경 금지 영역, 필요한 참고 파일을 찾는 방법을 넣는다.
스킬은 특정 작업을 수행하는 절차와 참고 자료를 재사용하는 단위다. 블로그 생성 스킬이라면 원자료 확인, 작성, 출처 점검, 공개 전 검사와 실패 처리까지 연결한다. 단순한 말투 지시와 실제 발행 권한을 섞으면 글쓰기 요청을 배포 승인으로 오해할 수 있다.
점진적 공개는 필요한 시점에 필요한 자료를 읽는 방식이다. 참조 경로를 안내하는 context pointer도 여기에 쓰인다. 포인터가 끊겼거나 실제 파일이 오래됐으면 잘못된 절차를 반복할 수 있다. Anthropic의 문맥 설계 글을 참고하되 자신의 저장소에서는 파일 존재와 지침 간 충돌을 직접 검사한다.
7. 테스트·리뷰·작업 패턴: 완료했다는 말을 검증한다
자동 검사는 타입 검사, 빌드, 테스트처럼 명시한 조건을 확인한다. 자동 리뷰는 규칙 기반 분석이나 모델을 이용한 검토를 포함할 수 있다. 두 용어의 범위를 팀에서 정해야 한다. 모델에게 코드를 읽혀 “문제없다”는 답을 받았다고 테스트를 실행한 것은 아니다.
인간 리뷰는 요구사항, 업무 맥락, 보안과 운영 영향을 판단하는 과정이다. human-in-the-loop는 그런 개입 지점을 포함한 방식이고 AFK는 사람이 키보드 앞에 계속 있지 않은 운영 상황을 뜻한다. 자리를 비워도 된다는 설정이 삭제·구매·배포 권한의 무제한 위임을 뜻하지 않도록 해야 한다. 바이브 코딩과 프로토타이핑을 택해도 실제 사용자 데이터를 처리할 때의 검증 책임은 남는다.
DX는 사람이 개발 도구를 사용하는 경험, AX는 에이전트가 자료와 도구를 활용하는 경험을 설명하는 말이다. 오류 메시지에 실행 위치와 실패 원인을 남기고 테스트를 한 명령으로 실행하게 하면 양쪽에 도움이 된다. Grilling처럼 가정을 질문으로 검토하는 작업은 명세를 확정하는 데 쓰되 이미 코드에서 확인할 사실을 사용자에게 반복해서 묻지 않는다.
검색 정렬이 계속 틀리면 요청한 날짜 기준, 실제 읽은 코드, 실행한 도구 결과, 재현 테스트 순서로 돌아간다. 어느 단계가 실패했는지 기록한 다음 그 부분만 바꾼다. 용어를 정확히 쓰는 목적은 기술 이름을 많이 아는 모습을 보이기보다 다음 확인 위치를 좁히는 데 있다.
참고자료
- Matt Pocock, AI Coding Dictionary: 용어를 구분하는 출발점. 본문의 검색 수정 사례는 필자가 구성했다.
- MCP 공식 소개: 연결 프로토콜의 범위.
- Anthropic, Building effective agents: 워크플로와 에이전트 구분.
- Anthropic, Effective context engineering: 문맥 관리 접근.
- Liu 외, Lost in the Middle: 긴 문맥 평가의 조건과 결과.