코딩 에이전트에게 일을 맡길 때 결과물보다 먼저 적을 것

코딩 에이전트에게 “이 기능을 구현해 주세요”라고 부탁하면 코드가 돌아올 수 있습니다. 하지만 어떤 파일을 바꿔도 되는지, 무엇을 성공으로 볼지, 어떤 검사를 실행했는지 빠져 있으면 결과를 검토하는 일이 오히려 어려워집니다. 작업을 맡길 때는 구현 아이디어보다 판단 기준과 제한을 먼저 공유하는 편이 낫습니다.

GitHub가 2026년 10월 발표한 개발자 인터페이스에 관한 글은 개발자가 도구를 하나씩 조작하는 시간보다 방향·맥락·제약을 정하고 결과를 검토하는 일이 중요해질 수 있다고 주장합니다. 이는 제품을 만드는 회사의 관점이며 독립된 직무 연구의 결론은 아닙니다. 다만 에이전트가 저장소를 읽고 파일을 편집하고 명령과 테스트를 수행하는 흐름을 생각할 때, 지시를 검증 가능한 작업 계약으로 적는다는 실용적인 질문을 던집니다. GitHub의 ambient intelligence 글을 제품사 관점으로 읽고 작업 지시의 기준을 정리하겠습니다.

요청을 결과와 완료 증거로 나눕니다

목표는 사용자가 관찰할 수 있는 결과로 씁니다. “코드를 정리해 주세요” 대신 “설정 화면에서 저장 후 새로고침해도 선택한 값이 유지되게 해 주세요”처럼 재현 가능한 상황을 적습니다. 원하는 결과와 그 결과를 확인할 증거를 연결하면, 에이전트가 실제 요청을 해결했는지 diff와 검사 결과로 검토할 수 있습니다.

완료 증거는 과업에 맞게 고릅니다. UI 수정이면 영향받는 동작, API 변경이면 요청·응답 예시와 관련 테스트, 문서 변경이면 링크와 명령의 유효성 같은 조건을 쓸 수 있습니다. 테스트를 실행할 수 없는 환경이라면 실행하지 못한 이유와 대신 확인한 범위를 보고하도록 요청해야 합니다.

변경 경계를 먼저 제한합니다

에이전트는 목표를 해결하려다 관련 없는 구조 개선까지 제안할 수 있습니다. 허용된 파일이나 모듈, 수정하지 말아야 할 설정, 공개 API의 호환 조건, 의존성 추가 여부를 명시하면 검토 범위를 줄일 수 있습니다. 이 조건은 무조건 파일 하나로 제한하라는 뜻이 아니라, 변경 이유가 요청과 연결되도록 하는 경계입니다.

• 수정 대상: 이번 작업에서 손댈 수 있는 기능이나 디렉터리를 적습니다.
• 보존 조건: 공개 동작, 데이터 형식, 보안 규칙 등 유지할 계약을 적습니다.
• 금지 사항: 무관한 포맷 변경, 비밀값 출력, 새 의존성 추가 등 금지할 일을 씁니다.
• 의존 작업: API나 설정 변경이 필요하면 구현 전에 이유와 영향을 요약하게 합니다.

요청 범위를 벗어나는 문제가 발견되면 자동으로 확대하지 말고 별도 제안으로 남기도록 하면, 한 번의 작업에서 리뷰해야 할 결정 수를 통제할 수 있습니다.

검증할 수 없는 조건은 합의 대상으로 남깁니다

성공 조건이 주관적이면 에이전트에게 코드를 돌려받아도 합격 여부를 판단하기 어렵습니다. “빠르게”, “깔끔하게”, “안전하게”라는 표현만 쓰지 말고 어떤 상황에서 어떤 결과가 나와야 하는지 가능한 범위에서 구체화합니다. 성능 목표라면 입력 데이터와 실행 환경을, 접근 제어라면 역할별 허용 동작을 명시해야 비교가 가능합니다.

모든 요구를 지시서만으로 해결할 수 있는 것은 아닙니다. 제품의 우선순위, 정책, 법적 요건처럼 결정권자의 판단이 필요한 부분은 미확정으로 표시하고, 에이전트가 임의로 선택하지 않도록 합니다. 기본값을 정해야 할 때는 그 이유와 가정을 답변에 드러내게 하십시오.

중단 조건과 보고 형식을 적습니다

테스트 실패 원인이 환경인지 코드인지 구별되지 않거나, 예상보다 많은 파일이 변경되거나, 민감 데이터나 외부 서비스 접근이 필요해지면 작업을 중단하고 알려야 합니다. 중단 기준이 없으면 에이전트는 성공을 만들기 위해 계속 다른 접근을 시도할 수 있습니다. 멈춰야 할 때 멈추는 것도 완료 조건의 일부입니다.

마지막 보고에는 변경 요약, 실제 실행한 검사, 실행하지 않은 검사, 남은 불확실성, 검토가 필요한 파일을 구분해 쓰도록 요청합니다. “완료했습니다”라는 문장보다 재현 가능한 증거가 더 유용합니다. 도구가 명령을 실행했다고 하더라도 출력과 변경 결과를 사람이 확인해야 합니다.

작은 일부터 지시 형식을 반복합니다

처음부터 모든 작업을 장황한 문서로 만들 필요는 없습니다. 작은 수정에서 목표, 경계, 성공 조건, 금지 사항, 보고 형식을 짧게 적고 누락된 정보가 어디서 생기는지 살펴보십시오. 같은 종류의 작업을 반복하면서 팀 템플릿으로 다듬으면 지시 길이를 늘리지 않고도 검토 품질을 높일 수 있습니다.

템플릿은 만능 프롬프트가 아닙니다. 작업마다 성공 조건과 위험이 다르므로 복사한 뒤 실제 요청에 맞게 고쳐야 합니다. 개인정보나 비밀값을 지시문에 넣지 말고, 저장소의 비신뢰 문서가 권한이나 정책을 바꾸는 근거가 되지 않도록 실행 환경도 점검하십시오.

완료 기준은 가능한 한 결과물을 확인하는 사람이 다시 따라 할 수 있어야 합니다. “테스트 통과”라는 보고만 받지 말고 실행한 명령과 관련 결과를 남기게 하십시오. 테스트를 실행하지 못했다면 실패, 미실행, 환경 제한을 각각 구분하고, 어떤 수동 확인이 남았는지도 적도록 합니다.

작업이 여러 단계로 나뉜다면 각 단계 끝에 변경 파일과 다음 단계의 전제 조건을 보고하게 하는 방법이 있습니다. 다만 보고서를 길게 만드는 것이 목적은 아닙니다. 다음 결정에 필요한 사실만 간결하게 공유하고, 보안이나 데이터 변경처럼 위험이 큰 단계에서 사람의 판단을 요청하도록 경계를 둡니다.

기존 테스트의 상태도 작업 전제에 넣으면 좋습니다. 이미 실패하는 검사가 있다면 새 변경의 실패와 혼동하지 않도록 기준 상태를 기록합니다. 작업 시작 시 저장소가 깨끗한지 확인하고, 다른 변경 사항이 보이면 이를 덮어쓰지 않도록 중단하거나 분리된 브랜치에서 작업하게 합니다.

지시서가 지나치게 긴 경우에는 상시 적용할 저장소 정책과 이번 작업에서만 필요한 조건을 나누어 관리합니다. 작업마다 중요한 성공 기준을 앞쪽에 두고, 배경 설명은 판단에 필요한 만큼만 제공하십시오. 짧더라도 서로 충돌하지 않는 지시가 복사한 장문의 템플릿보다 검토하기 쉽습니다.

마치며

에이전트에게 일을 맡길 때 결과물만 요청하면 판단 기준과 책임 경계가 비어 있게 됩니다. 목표와 완료 증거, 변경 범위, 중단 조건을 먼저 적고, 실행한 검사와 남은 불확실성을 보고받으십시오. 다음 작업 지시 하나에 “무엇을 바꾸지 말아야 하는가”와 “무엇을 확인하면 완료인가”를 추가해 보시기 바랍니다.