로컬 코딩 에이전트 작업 하네스 설계 예제

Node.js가 설치된 연습 폴더에서 src/label.mjs와 test/label.test.mjs를 만들어요. 예제 함수는 문자열 앞뒤 공백을 지우지만, 공백만 넣으면 빈 문자열을 반환해요. 이 예제의 요구사항은 빈 이름에 Untitled를 쓰는 거예요.

export function normalizeLabel(text) {
  return text.trim();
}

import test from 'node:test';
import assert from 'node:assert/strict';
import { normalizeLabel } from '../src/label.mjs';

test('trims ordinary names', () => {
  assert.equal(normalizeLabel('  Project  '), 'Project');
});
test('replaces an empty name', () => {
  assert.equal(normalizeLabel('   '), 'Untitled');
});

테스트를 먼저 실행하면 일반 문자열 검사는 통과하고 빈 이름 검사는 실패해요. 에이전트에는 이 실패와 원하는 반환값을 함께 전달하면 돼요. ‘코드를 개선해줘’보다 어떤 수정을 끝내야 하는지 분명해져요.

node --test test/label.test.mjs

프로젝트 지침에는 바꿔도 되는 파일과 실행할 테스트를 적어요. 아래 내용은 AGENTS.md를 읽는 에이전트에서 쓸 예제예요. 사용하는 제품이 다른 지침 파일을 읽으면 같은 내용을 그 파일에 넣고, 첫 수정 전에 적용한 지침과 수정할 파일을 말하게 해요.

수정 대상: src/label.mjs
요구사항: 공백을 제거한 결과가 비면 Untitled 반환
검증: node --test test/label.test.mjs
테스트 파일은 수정하지 말 것
네트워크 접근·배포·비밀 파일 열람 금지
완료 보고: 변경 파일, 테스트와 결과, 남은 문제

지침 파일과 함께 에이전트 설정의 실행 권한도 맞춰요. 이 연습에 필요한 도구는 두 파일을 읽고 함수를 수정하는 기능, 테스트 명령을 실행하는 터미널이에요. 네트워크나 배포 기능은 필요 없으니 허용 목록¹에서 제외하세요.

에이전트에 빈 이름 테스트를 통과시키도록 요청하고 src/label.mjs만 바꾸게 해요. 수정 뒤에는 같은 테스트를 다시 실행해요. 이 예제에서는 공백을 지운 값이 비어 있을 때만 Untitled를 반환하면 두 검사가 모두 통과해요.

export function normalizeLabel(text) {
  const label = text.trim();
  return label || 'Untitled';
}

마지막에는 함수와 테스트를 나란히 읽어요. 반환값을 고친 대신 테스트의 기대값을 바꾸지는 않았는지, 다른 파일을 건드리지는 않았는지 확인해요. 실패가 이어지면 전체를 다시 쓰게 하기보다 실패한 입력과 해당 함수의 변경부터 살펴보세요.

실제 저장소에서도 문제를 재현하는 입력, 관련 파일과 테스트, 결과 검토 순서를 유지하면 돼요. 삭제·배포·외부 전송은 필요한 시점에 따로 승인하고, 되돌릴 때도 이번 변경만 대상으로 삼아 다른 작업자의 수정은 보존해요.