연재: AI에게 일자리를 빼앗길 불안으로부터 시작하는 하네스(Harness) 작성 입문 제4회 - task_request /

연재: AI에게 일자리를 빼앗길 불안으로부터 시작하는 하네스(Harness) 작성 입문

전 24회(주 2회·12주간) | 제4회 / 24 이 연재는, AI로 인한 커리어 불안을 가진 프로그래머·SE를 대상으로, AI 에이전트를 안전하게 제어·검증·운용하기 위한 「하네스(Harness)」를 만드는 기술을 단계적으로 배우는 시리즈입니다.

이 기사는 연재 「연재: AI에게 일자리를 빼앗길 불안으로부터 시작하는 하네스 작성 입문」의 제4회입니다.

제2회에서는 최소 구성(AI 에이전트 + MCP 서버 + task_request / task_result)을 Mermaid 다이어그램으로 설계하였고, 제3회에서는 「사용한다」와 「운용한다」의 차이를 정리했습니다. 이번에는 그 최소 구성의 핵심인 task_request / task_result의 설계에 대해 정리합니다.

이 기사에서 다루는 불안은 다음과 같습니다.

AI 에이전트에게 자연어로 지시를 내리고 있지만, 지시의 재현성이 낮고 결과의 품질이 안정적이지 않다. 구조화하는 방법을 모르겠다.

이러한 불안은 자연스럽습니다. 자연어 프롬프트(Prompt)는 유연하지만, 동일한 지시라도 결과가 달라집니다. 업무에서는 「어제와 오늘 결과가 다르다」는 상황은 곤란합니다.

이 기사에서는 AI에 대한 지시와 결과를 JSON으로 구조화하는 「계약 (Contract)」의 설계 방법을 제시합니다.

• AI 에이전트에 대한 지시의 재현성 문제로 고민 중인 프로그래머
• API 설계나 인터페이스 정의 경험이 있는 SE
• AI의 입출력을 구조화하고 싶지만, 어떤 JSON 스키마(Schema)로 해야 할지 망설여지는 엔지니어

결론부터 말씀드리면, AI 에이전트에 대한 지시와 결과를 JSON으로 구조화하여 「계약」으로 취급함으로써 재현성·검증성·로그 가능성을 향상시킨다 입니다.

요점은 다음과 같습니다.

• task_request로 「무엇을 해주길 원하는가」를 구조화하여 지시의 모호함을 줄인다
• task_result로 「무엇이 돌아왔는가」를 구조화하여 검증과 로그를 가능하게 한다
• API 설계 경험이 있는 사람에게 이 「입출력의 계약화」는 익숙한 작업이다

자연어 프롬프트는 유연하지만 다음과 같은 문제가 있습니다.

문제	구체적인 예시
모호성	「적당히 만들어줘」에서 「적당히」가 정의되어 있지 않음
...

API 설계에서는 요청(Request)과 응답(Response)의 형식을 명확하게 정의합니다. REST API라면 요청 바디(Request Body)와 응답 스키마(Response Schema), gRPC라면 Protocol Buffers로 정의합니다.

AI 에이전트도 마찬가지입니다. 「무엇을 전달하고 무엇이 돌아오는가」를 JSON으로 정의함으로써 「계약」을 할 수 있습니다. 이것이 task_request / task_result 입니다.

task_request / task_result의 설계는 API 설계 경험이 그대로 활용되는 영역입니다.

기존 경험	task_request / task_result 설계에서의 활용 방법
REST API의 요청/응답 설계	task_request의 입력 필드와 task_result의 출력 스키마 정의
...

「입력과 출력을 명확히 정의하고, 이상 계통(Exception case)을 포함하여 설계한다」는 경험은 AI 하네스 설계에서 그대로 사용할 수 있습니다.

다음은 task_request의 필수 필드입니다.

필드	타입	설명
task_id	string	태스크의 고유 식별자. 로그 및 재실행 추적에 사용
task_type	string	태스크의 종류. 에이전트가 처리를 전환하는 기준
input	object	태스크에 필요한 입력 데이터

다음은 운용이 진행됨에 따라 추가하는 필드입니다. 처음부터 전부 넣을 필요는 없습니다.

필드	타입	설명	추가 시기 기준
constraints	array	출력의 제약 조건	처음부터
quality_gate	object	품질 게이트(Quality Gate) 기준	제17~18회
model_preference	string	사용 LLM 지정	제11~12회
log_level	string	로그 출력 상세도	제13~14회
approval_required	boolean	인간의 승인이 필요한지 여부	제15~16회
timeout_seconds	integer	타임아웃 설정	필요에 따라

다음은 실용적인 task_request의 JSON 템플릿입니다. 이것이 이번 회차의 가장 중요한 결과물입니다.

{
"task_request": {
"task_id": "review_api_design_001",
...

이 JSON을 보고 "이것은 API의 요청 본문(Request Body)과 비슷하다"라고 느끼신 분도 계실 것입니다. 맞습니다. API 설계 경험이 그대로 활용됩니다.

필드	타입	설명
task_id	string	대응하는 task_request의 task_id
status	string	completed / failed / partial
output	object	태스크(Task) 실행 결과

필드	타입	설명
error	object	에러 정보 (status가 failed일 때)
metadata	object	실행 시간·사용 모델·토큰 수 등
warnings	array	완료되었으나 주의가 필요한 사항

앞서 살펴본 task_request에 대응하는 task_result의 예시입니다.

{
"task_result": {
"task_id": "review_api_design_001",
...

AI 에이전트가 실패했을 경우에도 구조화된 결과가 반환되도록 설계합니다. 이는 API의 에러 응답(Error Response) 설계와 동일한 사고방식입니다.

{
"task_result": {
"task_id": "review_api_design_001",
...

정상 케이스(Normal Case)뿐만 아니라 이상 케이스(Abnormal Case)도 설계함으로써, 장애 발생 시 조사나 자동 재시도(Retry)가 가능해집니다.

task_request는 자연어 프롬프트(Natural Language Prompt)를 대체하는 것이 아닙니다. 두 가지를 병용합니다.

역할	담당
"무엇을 해주길 원하는가"의 구조화	task_request (JSON)
...

task_request가 "계약서"이고, 프롬프트가 "구두로 하는 보충 설명"이라고 생각하면 이해하기 쉽습니다. 계약서가 있기 때문에 "무엇을 약속했는지"가 명확해지며, 검증과 로그 기록이 가능해집니다.

주의점	이유	대책
처음부터 필드를 너무 많이 채워 넣지 말 것	복잡한 스키마(Schema)는 운영 부하가 높음	필수 필드부터 시작하여 필요에 따라 추가
task_id의 명명 규칙을 정할 것	로그 검색 시 규칙이 없으면 찾을 수 없음	{task_type}_{target}_{연번}과 같은 규칙을 정함
에러 발생 시의 task_result도 반드시 설계할 것	이상 케이스가 설계되지 않으면 장애 조사가 불가능함	status + error 필드를 반드시 포함

• 위의 task_request JSON 템플릿을 자신의 업무에 맞춰 다시 작성하기
• 대응하는 task_result (정상 케이스 + 에러 케이스)도 작성하기
• 작성한 JSON을 GitHub 리포지토리의 templates/ 디렉토리에 저장하기

이 글에서는 AI 에이전트에 대한 지시와 결과를 JSON으로 구조화하는 task_request / task_result 설계에 대해 정리했습니다.

중요한 것은, 자연어 프롬프트만으로는 확보할 수 없는 "재현성", "검증성", "로그 가능성"을 JSON을 통한 구조화로 실현하는 것입니다.

API 설계나 인터페이스 정의 경험이 있는 사람에게 이 "입출력의 계약화"는 익숙한 작업입니다. 그 경험을 AI 하네스(Harness) 설계에 활용해 주세요.

제5회: SE의 설계 경험을 AI 에이전트 제어에 전용하기 (화요일 공개 예정)

다음 회차에서는 SE의 설계 경험을 AI 하네스 설계에 어떻게 전용할 수 있는지 더 구체적으로 정리합니다.

다음 회차 다룰 내용:

• 요구사항 정리·책임 분리·인터페이스 설계 경험을 AI 하네스에 전용하는 대응표
• "인간이 설계하고, AI가 실행한다"라는 역할 분담의 사고방식
• 설계 경험을 활용할 수 있는 구체적인 시나리오

다음 회차의 결과물:

• 대응표 (SE 경험 → AI 하네스 설계로의 전용 맵)

다음 회차 전까지 시도해 보면 좋은 것:

• 이번에 작성한 task_request JSON을 GitHub에 저장하기
• 자신의 설계 경험 중에서 "AI 하네스에 활용할 수 있겠다"라고 느껴지는 것을 하나 생각해 두기

회차	제목	상태
1	AI에게 일자리를 빼앗길 불안으로부터 「하네스(Harness) 작성」을 배우는 이유	✅
...	4	task_request / task_result로 AI 에이전트의 업무를 계약화하기 (이 기사)
5	SE의 설계 경험을 AI 에이전트 제어에 전용하기	차회
6	하네스용 디렉터리 구성과 README 만들기	─
...	총 24회의 연재를 예정하고 있습니다	─

연재 정보

• 연재명:
  연재: AI에게 일자리를 빼앗길 불안으로부터 시작하는 하네스(Harness) 작성 입문 - 총 24회 (12주간 · 주 2회)
• 게시 요일: 화요일 (커리어 · 설계 · 개념) / 금요일 (구현 · 검증 · 템플릿)