[번역] 코딩 에이전트는 일이 끝났다는 걸 어떻게 알까? 자바스크립트 97줄로 살펴보기
Soshy··조회수 —


고친 건 한 줄이었다. 그 아래에 “완료. 이제 cartTotal에 수량이 반영됩니다.”라는 메시지가 떴다. 곧이어 테스트를 돌렸더니 세 개 중 두 개에서 NaN이 나왔다. 그중 하나는 고치기 전엔 통과했던 테스트다.
이 글을 쓰려고 만든 작은 코딩 에이전트에서 실제로 나온 결과다. 외부 라이브러리 없이 자바스크립트 97줄로 짰다. 이 에이전트는 작업이 끝났는지 모델에게 묻지 않는다. 프로젝트를 직접 확인한다.
코드를 한 줄씩 살펴보면서 에이전트가 서로 다른 두 가지 가짜 ‘완료’를 어떻게 걸러 내는지, 실제 도구에는 여기에 어떤 기능이 더 들어가는지 알아보자.
작업이 끝났다고 누가 판단할까?
코딩 에이전트는 모델이 다 했다고 말하면 멈출 것 같다. 채팅에서 보면 실제로 그렇게 느껴진다. 뭔가를 부탁하면 답이 오고, 마지막에는 무엇을 했는지 자신 있게 요약해 준다.
하지만 모델의 ‘완료’는 그럴듯하게 생성한 문장이다. 코드를 돌려 보고 내린 결론이 아니다. 모델 바깥에서 코드를 실행해 결과를 돌려주지 않으면, 모델이 말하는 ‘완료’는 결국 ‘이렇게 고치면 될 것 같다’는 뜻이다.
Anthropic의 가이드 효과적인 에이전트 만들기 에서는 에이전트가 작업하는 매 단계마다 실행 환경에서 확인한 사실이 필요하다고 설명한다. 도구가 반환한 값이나 코드를 실행해서 얻은 결과가 그 예다. 코딩이 에이전트에 잘 맞는 것도 자동화된 테스트로 결과를 검증할 수 있어서다. 최대 반복 횟수처럼 어디서 멈출지 정해 두는 것도 흔하다.
그래서 눈여겨볼 곳은 모델을 둘러싼 루프다. 이 글의 루프는 앉은자리에서 다 읽을 수 있을 만큼 짧다.
미리 밝혀 두자면, 이 글을 쓰는 데 언어 모델을 실제로 돌리지는 않았다. 대신 미리 정해 둔 수정안을 순서대로 반환하는 함수를 넣었다. 처음에는 틀린 수정안을, 그다음에는 맞는 수정안을 내놓는다. 덕분에 인터넷에 연결하지 않고도 언제든 같은 결과를 재현할 수 있다. 이 글에서 볼 일은 모두 모델이 답한 뒤에 벌어지니 그걸로 충분하다.
버그 하나와 작업 명세
먼저 에이전트에게 맡길 일이 있어야 한다. 이 ‘프로젝트’의 전부는 일부러 버그를 넣어 둔 함수 하나다.
export function cartTotal(items) {
return items.reduce((sum, item) => sum + item.price, 0);
}
상품 가격을 모두 더하지만 장바구니에 각각 몇 개가 들어 있는지는 계산에 넣지 않는다. 프로젝트의 테스트 세 개 중 이 테스트가 실패한다.
test('quantity multiplies the price', () => {
const items = [
{ name: 'pen', price: 2, quantity: 3 },
{ name: 'pad', price: 5, quantity: 1 },
];
assert.equal(cartTotal(items), 11);
});
에이전트가 손을 대기 전에 작업 명세부터 적는다. 무엇을 고칠지, 어느 파일을 고쳐도 되는지, 제대로 고쳤는지 어떻게 확인할지를 담는다.
const task = {
goal: 'cartTotal must multiply each price by its quantity',
files: ['cart.mjs'],
acceptance: 'node --test exits with code 0',
};
세 번째 항목은 생각보다 중요하다. 어떤 검증을 통과해야 하는지 작업 명세에 써 두면, 코드를 한 줄도 고치기 전에 어디까지 해야 끝인지 정할 수 있다.
프로젝트를 직접 돌려 본다
루프의 핵심은 이 함수다. 자식 프로세스에서 프로젝트의 테스트를 돌리고 결과를 알려 준다.
// 프로젝트의 테스트를 돌리고 다음 시도에 알려 줄 내용만 남긴다.
export function runChecks(dir) {
const env = { ...process.env };
delete env.NODE_TEST_CONTEXT; // 다른 테스트 안에서 호출해도 동작하도록 한다.
const args = ['--test', '--test-reporter=tap'];
const options = { cwd: dir, env, encoding: 'utf8' };
const run = spawnSync(process.execPath, args, options);
const failures = (run.stdout + run.stderr)
.split('\n')
.map((line) => line.trim())
.filter((line) => /^(not ok|expected:|actual:)/.test(line));
return { passed: run.status === 0, failures };
}
spawnSync는 현재 프로세스를 실행한 Node 바이너리(process.execPath)로 별도의 Node 프로세스를 띄우고, 끝날 때까지 기다린다. 프로젝트 폴더에서 node --test를 실행하면 Node가 테스트 파일을 찾아 내장 테스트 러너로 돌린다. 전부 통과하면 자식 프로세스가 종료 코드 0을 반환하고, 하나라도 실패하면 0이 아닌 값을 반환한다. passed는 그 숫자 하나로 결정된다.
실행 환경이 달라도 출력 형식이 같도록 TAP 리포터를 지정했다. 출력에서 남기는 건 수정에 필요한 정보뿐이다. 어떤 테스트가 실패했는지, 어떤 값을 기대했고 실제로는 뭐가 나왔는지다. NODE_TEST_CONTEXT를 지우는 데도 이유가 있다. Node는 테스트 파일을 실행할 때 이 환경 변수를 설정하는데, 그 상태에서 node --test를 실행하면 처음부터 새로 실행할 때와 다르게 동작한다. 이 줄을 빼 봤더니 루프를 검증하는 테스트 여덟 개 중 네 개가 실패했다.
아무리 그럴듯하게 말해도 종료 코드는 바뀌지 않는다.
조금만 고치고, 필요하면 되돌린다
모델이 파일을 통째로 다시 쓰게 두지 않는다. 어느 텍스트를 무엇으로 바꿀지만 한 건씩 제안하게 한다. 바꿀 텍스트가 파일에서 정확히 한 번 나올 때만 루프가 수정을 적용한다.
// 텍스트를 찾아 한 곳만 바꾼다. 바꿀 텍스트는 정확히 한 번 나와야 한다.
export function applyEdit(dir, edit, originals) {
const file = path.join(dir, edit.file);
const before = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
if (before.split(edit.find).length !== 2) {
return { ok: false, reason: `"${edit.find}" must match exactly once` };
}
if (!originals.has(file)) originals.set(file, before);
fs.writeFileSync(file, before.replace(edit.find, () => edit.replace));
const diff = { file: edit.file, removed: edit.find, added: edit.replace };
return { ok: true, diff };
}
// 이번 시도에서 건드린 파일을 모두 원래대로 돌려놓는다.
export function rollBack(originals) {
for (const [file, text] of originals) fs.writeFileSync(file, text);
originals.clear();
}
일치하는 곳이 없으면 실제 파일 내용이 모델의 예상과 다르다는 뜻이다. 두 곳에서 일치하면 어느 쪽을 바꿔야 할지 알 수 없다. 두 경우 모두 수정을 거부하고 그 이유를 모델에 알려 준다.
놓치기 쉬운 부분이 두 군데 있다. 먼저 바꿔 넣을 텍스트를 문자열로 바로 넘기지 않고, () => edit.replace라는 함수로 넘긴다. String.prototype.replace에 문자열을 바로 넘기면 $& 같은 문자 조합을 특별하게 처리하는데, 코드에는 달러 기호가 흔히 들어가기 때문이다. 또 파일을 처음 건드릴 때는 원래 내용을 Map에 저장해 둔다. 잘못 고쳤을 때 수정 전 상태로 돌아가기 위해서다.
되돌릴 수 없다면 매번 맞아야 한다. 되돌릴 수 있다면 시도 중 한 번만 맞으면 된다.
수정안을 받아 적용하고 검증한다
이제 메인 함수를 보자. 먼저 앞부분이다.
const list = (items) => items.map((item) => `\n ${item}`).join('');
export async function runTask({ dir, task, model, maxAttempts = 4, log }) {
const baseline = runChecks(dir);
log(`baseline checks:${list(baseline.failures) || ' all green'}`);
let feedback = baseline.failures;
let sentBack = false;
const originals = new Map();
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
const proposal = await model({ task, feedback, attempt });
log(`attempt ${attempt}: ${proposal.note}`);
const edit = applyEdit(dir, proposal.edit, originals);
if (!edit.ok) {
feedback = [edit.reason];
log(` edit refused: ${edit.reason}`);
continue;
}
log(` - ${edit.diff.removed}`);
log(` + ${edit.diff.added}`);
log(` model says: "${proposal.claim}"`);
const checks = runChecks(dir);
if (!checks.passed) {
feedback = checks.failures;
log(` checks say: FAILED${list(checks.failures)}`);
rollBack(originals);
continue;
}
log(' checks say: passed');
아무것도 고치기 전에 테스트부터 한 번 돌린다. 그래야 모델에 실패를 말로 설명하는 대신 실제로 어떤 오류가 났는지 보여 줄 수 있다. 그다음부터는 수정안을 받아 적용하고, 모델이 뭐라고 답했는지 출력한 뒤 테스트를 돌린다. 테스트가 실패하면 실패 내역을 다음 시도에 넘기고, 방금 한 수정은 되돌린다.
proposal.claim에 주목해 보자. 로그에 찍고 끝이다. 루프는 이 값으로 아무것도 판단하지 않는다.
첫 번째 예에서는 모델 역할을 하는 함수가 틀린 수정안을 먼저 내놓고, 다음에 맞는 수정안을 내놓는다. Node v22.23.5에서 데모를 실행했을 때 나온 출력이다.
baseline checks:
not ok 3 - quantity multiplies the price
expected: 11
actual: 7
attempt 1: multiply the price by the quantity
- sum + item.price,
+ sum + item.price * item.qty,
model says: "Done. cartTotal now accounts for quantity."
checks say: FAILED
not ok 2 - single items are added up
expected: 7
actual: NaN
not ok 3 - quantity multiplies the price
expected: 11
actual: NaN
attempt 2: multiply the price by item.quantity
- sum + item.price,
+ sum + item.price * item.quantity,
model says: "Done. cartTotal multiplies price by quantity."
checks say: passed
review says: approved
result: done=true attempts=2
첫 번째 수정안은 바뀐 줄만 보면 그럴듯하다. 하지만 item.quantity를 써야 할 자리에 item.qty를 썼다. 모델은 자신 있게 다 고쳤다고 했지만, 돌려 보니 테스트 두 개가 실패했다. 그중 하나는 수정 전에는 통과하던 테스트다. actual: NaN을 보면 존재하지 않는 속성을 읽었을 가능성을 짚어 볼 수 있다. 두 번째 시도에 들어갈 때 모델 역할을 하는 함수가 받는 게 바로 이 실패 내역이다.
모델은 두 번 다 끝났다고 했다. 루프는 두 번 다 직접 확인했고, 그중 한 번만 완료로 처리했다.
테스트가 엉뚱한 이유로 통과하면?
실패하는 테스트를 통과시키는 손쉬운 방법이 있다. 테스트 자체를 고치는 것이다. 그래서 루프는 테스트가 통과한 뒤에도 한 번 더 확인한다.
// 작업 명세, 변경 내역, 검증 결과만 받아 한 번 더 검토한다.
export function review({ task, diff, checks }) {
const problems = [];
if (!checks.passed) problems.push('the checks are not passing');
if (/\.(test|spec)\.[cm]?[jt]sx?$/.test(diff.file)) {
problems.push(`the diff edits a test file (${diff.file})`);
}
if (!task.files.includes(diff.file)) {
problems.push(`the diff touches ${diff.file}, which the plan did not list`);
}
return { approved: problems.length === 0, problems };
}
검토 단계에는 작업 명세, 변경 내역, 검증 결과만 넘어간다. 모델과 어떤 대화를 했는지, 모델이 어떤 근거를 댔는지, 작업을 끝냈다고 했는지는 전달하지 않는다. 아래 코드는 테스트가 모두 통과했을 때 실행되는 루프의 뒷부분이다.
const verdict = review({ task, diff: edit.diff, checks });
if (verdict.approved) {
log(' review says: approved');
return { done: true, attempts: attempt, diff: edit.diff };
}
log(` review says: SENT BACK${list(verdict.problems)}`);
rollBack(originals);
if (sentBack) {
return { done: false, attempts: attempt, reason: 'review said no twice' };
}
sentBack = true;
feedback = verdict.problems;
}
return { done: false, attempts: maxAttempts, reason: 'out of attempts' };
}
두 번째 예에서는 처음에 내놓는 수정안을 바꿨다. cartTotal은 그대로 두고, 실패하는 테스트의 기댓값을 버그가 있는 코드가 반환하는 합계로 바꾼다.
attempt 1: update the expected total in the test
- assert.equal(cartTotal(items), 11);
+ assert.equal(cartTotal(items), 7);
model says: "Done. All tests pass now."
checks say: passed
review says: SENT BACK
the diff edits a test file (cart.test.mjs)
the diff touches cart.test.mjs, which the plan did not list
attempt 2: multiply the price by item.quantity
- sum + item.price,
+ sum + item.price * item.quantity,
model says: "Done. cartTotal multiplies price by quantity."
checks say: passed
review says: approved
result: done=true attempts=2
테스트는 통과했다. 앞 절에서 본 기준만 적용했다면 여기서 끝났을 것이다. 하지만 변경 내역을 검토하니 작업 명세에 없던 테스트 파일이 바뀌어 있었다. 검토에서 반려하자 루프는 테스트를 원래대로 돌려놓고 다음 시도로 넘어갔다.
테스트 결과를 보면 통과 여부를 알 수 있다. 변경 내역을 보면 왜 통과했는지 따져 볼 수 있다.
이 예제에서는 규칙 세 가지로 검토한다. 실제 에이전트에서는 보통 앞선 대화 내용을 빼고 모델을 새로 호출한다. Anthropic 가이드에서는 이 방식을 ‘평가자-최적화 패턴’이라고 부른다. 한 번은 결과물을 만들고, 또 한 번은 그 결과물을 평가한다. 이 예제에서 검토를 거쳐 다시 작업할 기회는 한 번뿐이다. sentBack이 없으면 고집 센 양쪽이 배터리가 다 닳을 때까지 실랑이를 벌일 수 있다.
루프 전체에도 횟수 제한이 있다. 모델 역할을 하는 함수가 매번 같은 오답을 내놓으면 이렇게 끝난다.
result: done=false attempts=4 reason="out of attempts"
네 번 시도했고 수정은 모두 되돌렸다. 결과는 ‘미완료’다. 실패했다고 말할 줄 아는 에이전트가 무슨 일이 있어도 다 했다고 하는 에이전트보다 낫다.
이 예제가 어디까지 통할까?
97줄로 할 수 있는 일에는 한계가 있다.
- 실제 모델을 붙여 보지 않았다. 실제 모델은 형식이 잘못된 수정안을 돌려주기도 하고, 엉뚱한 파일을 고르기도 한다. 한 곳만 고치라고 했는데 다섯 곳을 고칠 수도 있다. 텍스트가 정확히 한 번 일치하는지 확인하고 허용된 파일 목록을 검사하면 일부는 걸러 낼 수 있다. 다만 이 루프는 미리 준비한 수정안으로만 돌려 봤다.
- 테스트가 놓치는 버그는 루프도 놓친다. 예제에서 수량을 확인하는 테스트를 지우면 버그가 그대로 남아 있어도 첫 검증부터 통과한다. 이런 루프를 쓰면 테스트가 허술할 때 치르는 대가가 더 커진다.
- 검토 규칙이 단순하다. 작업에 따라 테스트를 바꿔야 할 때도 있다. 이 예제에서는 작업 명세에 적힌 파일이라도 테스트 파일이면 수정을 반려한다.
- 한 번 고칠 때마다 전체 테스트를 돌린다. 세 개뿐이라면 괜찮다. 큰 프로젝트라면 수정한 부분과 관련된 테스트부터 돌리고, 작업을 끝내기 전에 전체 테스트를 돌리는 편이 낫다.
- 프로젝트 코드를 실제로 실행한다.
node --test를 돌리면 프로젝트 안의 코드가 실행된다. 실제 에이전트라면 테스트 코드와 모델이 실행해 달라고 요청한 명령이 어디까지 접근할 수 있는지 제한해야 한다. - 직접 수정한 파일만 되돌린다. 테스트나 빌드 중에 새로 생긴 파일은 추적하지 않는다.
이런 차이를 보면 예제의 아이디어를 내 저장소에 안심하고 쓸 수 있는 도구로 만들기까지 얼마나 손이 더 가는지 알 수 있다.
실제 에이전트에는 무엇이 더 들어갈까?
같은 루프를 실제 도구로 구현한 예로 macOS용 오픈 소스 코딩 에이전트 Local Kovach가 있다. 먼저 밝혀 둘 게 있다. 내 GitHub 계정에 있는 프로젝트다. 아래 내용은 글을 쓰는 시점의 README를 바탕으로 정리했다. 위 예제는 리눅스에서 돌렸고 Kovach는 Mac 앱이라, 이 글을 쓰면서 앱을 직접 실행해 보지는 않았다.
README에 따르면 Local Kovach는 Apple Silicon Mac용 데스크톱 앱이다. 모델과 코드, 대화 기록, 앱이 작업하면서 배운 내용이 모두 사용자 기기에 남는다. oMLX나 OpenAI와 호환되는 다른 로컬 서버를 통해 모델을 실행하며, 요구 사양은 통합 메모리 32GB 이상이다.
작업 순서는 예제와 비슷하다.
- 먼저 작업 명세와 계획을 작성한다. 요청을 받으면 목표, 산출물, 완료 기준을 확인할 방법, 작업에 깔린 가정을 짧은 티켓으로 정리한다. 무엇을 바꿀지 계획도 미리 보여 준다. 예제의
task객체를 실제 작업에 맞게 확장한 셈이다. - 수정 후 검증한다. 프로젝트의 타입 검사, 린트, 테스트를 실행한다. 하나라도 실패하면 오류를 모델에 돌려준다. 예제의
runChecks가 테스트만 돌렸다면, 여기서는 세 가지를 확인한다. - 완료 전에 한 번 더 검토한다. 별도의 검토 단계에서 작업 명세, 변경 내역, 검증 결과만 보고 판단한다. 다시 작업하라고 돌려보낼 수 있는 건 한 번이다. 예제의
review와sentBack에 해당한다. - 작업하면서 얻은 내용과 공식 문서도 관리한다. 앱이 기억해 둘 내용은 검토함에 제안으로 들어가고, 사용자가 승인해야 저장된다. 프로젝트에서 쓰는 라이브러리 버전에 맞춰 공식 문서를 찾을 수 있는 색인도 있다.
README에는 아직 초기 단계라는 점도 적혀 있다. 서명된 릴리스가 없어 소스에서 직접 빌드해야 하고, 인터페이스도 계속 바뀌고 있다. 매개변수가 350억 개인 로컬 모델로 최첨단 모델 수준의 성능을 기대하기 어렵다는 점도 설계에 반영했다. 반드시 해야 하는 일은 프롬프트에 적어 두는 데 그치지 않고, 도구가 직접 실행하거나 루프에서 강제한다.
이 글의 요지는 그 마지막 문장에 담겨 있다. 모델에 기대하는 게 적을수록 루프에 맡기는 일이 많아진다.
README에 따르면 Kovach라는 이름은 대장장이라는 뜻의 보스니아어 kovač 에서 따왔다. 라이선스는 Apache-2.0이다.
지금 쓰는 도구에서 해 보기
이 방법을 써 보려고 에이전트를 직접 만들 필요는 없다. 다음에 AI 코딩 도구가 다 끝냈다고 하면, 요약부터 읽는 대신 루프가 하던 일을 해 보자. 직접 검증을 돌리고, 변경 내역을 열어 review가 확인하는 두 가지를 보면 된다. 테스트를 바꿨는가? 요청에서 언급하지 않은 파일을 바꿨는가?
루프를 직접 돌려 보고 싶다면, 위에 나온 루프의 코드 조각을 모으면 맨 위의 import 세 줄을 제외한 파일 전체가 된다. model은 작업 명세와 가장 최근의 피드백을 받는 비동기 함수다. 내가 미리 짜 둔 함수 자리에 실제 API 호출을 넣으면 된다. 메모리가 충분한 Apple Silicon Mac이 있고 초기 버전의 소프트웨어를 써 볼 여유가 있다면 Local Kovach도 있다. 같은 아이디어에 실제 도구로 쓰기 위한 기능을 얼마나 더 얹었는지는 README에서 볼 수 있다.
AI 도구가 ‘완료’라고 해서 믿었는데, 막상 보니 일이 끝나지 않았던 적이 있는가? 어떤 검증을 했다면 그 자리에서 알아챌 수 있었을까?