작업 명세 쓰기: 대상, 변경, 제약, 소유권, 완료 증거

작업 명세는 코딩 에이전트에게 일을 맡길 때 무엇을 어디서 바꾸고, 무엇을 지키며, 어느 파일까지 만질 수 있고, 무엇을 보여 주면 끝난 것으로 볼지를 적은 지시서입니다. 대상, 변경, 제약, 소유권, 완료 증거 다섯 항목으로 쓰면 결과를 한 번에 판정할 수 있습니다.

같은 말:작업 명세에이전트 지시서코딩 에이전트 프롬프트 템플릿완료 조건인수 조건

홍승협(준이아빠)게시 2026.10.03코스 3 / 8번째 개념

새로 올라온 개념이에요. 먼저 읽어 보고 퀴즈도 풀어 보세요

#AI #바이브코딩 #자동화

🤔 "로그인 버그 고쳐 줘"라고 맡겼더니 결과를 판정할 수 없을 때
🔑 작업 명세의 정의
📝 다섯 항목과 각 항목이 답하는 질문
🎯 대상과 변경: 한 문장으로 확인할 수 있게
🚧 제약과 소유권: 하지 말아야 할 것과 만지지 말아야 할 곳
✅ 완료 증거: 다시 실행할 수 있는 형태로
📄 명세 한 장의 예시
⚠️ 명세를 쓸 때 자주 하는 실수
❓ 자주 묻는 질문
📋 3줄 요약
📚 참고 자료

🤔 "로그인 버그 고쳐 줘"라고 맡겼더니 결과를 판정할 수 없을 때

에이전트에게 "로그인 버그 고쳐 줘"라고 맡기면 한참 뒤에 "수정했습니다"라는 보고가 옵니다. 그런데 무엇을 고쳤는지 보려고 변경 내역을 열면 로그인 함수뿐 아니라 설정 파일과 테스트 파일까지 바뀌어 있고, 버그가 정말 고쳐졌는지는 직접 재현해 봐야 압니다. 여러 에이전트에게 이런 식으로 일을 맡기면 결과를 확인하는 시간이 맡기기 전보다 더 걸립니다.

문제는 맡긴 문장에 판정 기준이 없다는 데 있습니다. 무엇을 바꾸면 되는지, 어디까지 만져도 되는지, 무엇을 보여 주면 끝인지가 적혀 있지 않으니 에이전트도 알아서 정하고, 받는 쪽도 판정할 근거가 없습니다. 이 편에서는 에이전트에게 넘기는 작업 명세를 다섯 항목으로 쓰는 방법을 정리합니다. 한 기능 전체의 목적을 적는 문서는 intent.md에서 다뤘고, 여기서는 그보다 작은 단위인 작업 하나의 지시서를 다룹니다.

🔑 작업 명세의 정의

작업 명세는 코딩 에이전트에게 일을 맡길 때 무엇을 어디서 바꾸고, 무엇을 지키며, 어느 파일까지 만질 수 있고, 무엇을 보여 주면 끝난 것으로 볼지를 적은 지시서입니다.

앤트로픽은 멀티 에이전트 리서치 시스템을 소개하며 이 지시서의 필요를 직접 설명했습니다. 작업자마다 목표와 결과 형식, 쓸 도구와 자료의 안내, 분명한 작업 경계가 필요하고, 자세한 작업 설명이 없으면 에이전트가 같은 일을 겹쳐 하거나 빈틈을 남기거나 필요한 정보를 찾지 못한다는 내용입니다. 초기 버전에서 "반도체 부족 현상을 조사하라"처럼 짧게 지시했더니 작업자들이 같은 검색을 되풀이했다는 사례도 함께 들었습니다.

📝 다섯 항목과 각 항목이 답하는 질문

항목	답하는 질문	약한 예	판정할 수 있는 예
대상	어느 저장소, 어느 브랜치, 어느 파일에서	로그인 쪽	`src/lib/auth.ts`의 `login()` 함수, 브랜치 `fix/login-timeout`
변경	무엇이 어떻게 달라져야 하는지	버그 고치기	비밀번호가 틀렸을 때 5초 대기 없이 바로 오류 메시지를 돌려준다
제약	무엇을 지키고 무엇을 하지 않는지	깔끔하게	새 라이브러리를 설치하지 않는다, 기존 테스트를 고치거나 지우지 않는다
소유권	어느 파일까지 만질 수 있는지	필요한 곳	`auth.ts`와 그 테스트 파일만 수정, 설정 파일과 다른 폴더는 읽기만
완료 증거	무엇을 보여 주면 끝인지	잘 되면	`npm test` 실패 0건, 바꾼 파일 목록과 테스트 출력 마지막 20줄 보고

다섯 항목은 앤트로픽이 든 위임의 조건과 겹칩니다. 대상과 변경이 목표를, 제약과 소유권이 작업 경계를, 완료 증거가 결과 형식을 맡습니다. 쓸 도구와 자료는 제약이나 대상 항목 안에 함께 넣습니다.

🎯 대상과 변경: 한 문장으로 확인할 수 있게

대상은 파일 경로와 함수 이름까지 적습니다. 클로드 코드 모범 사례 문서도 구체적인 파일을 가리키고, 제약을 적고, 따라 할 예시 코드의 위치를 알려 주라고 권하며, 지시가 정확할수록 고칠 일이 줄어든다고 설명합니다. 에이전트가 파일을 찾으며 쓰는 시간과 토큰이 그만큼 줄어듭니다.

변경은 무엇이 달라져야 하는지를 관찰할 수 있는 모습으로 적습니다. "성능 개선"보다 "목록 첫 화면이 2초 안에 뜬다", "버그 수정"보다 "비밀번호가 틀리면 바로 오류를 돌려준다"처럼 적으면 완료 증거로 곧바로 이어집니다. 같은 문서는 변경 내역을 한 문장으로 설명할 수 있을 만큼 작은 일이면 계획 단계를 건너뛰어도 된다고 안내하는데, 변경 항목이 한 문장으로 써지지 않는다면 작업을 더 쪼갤 신호로 보는 편이 낫습니다.

🚧 제약과 소유권: 하지 말아야 할 것과 만지지 말아야 할 곳

제약에는 지켜야 할 규칙과 하지 말아야 할 일을 적습니다. 특히 테스트와 검사를 건드리지 말라는 문장은 빠뜨리지 않습니다. 에이전트가 테스트를 고쳐 통과시키는 보상 해킹을 막는 가장 싼 방법이 지시문 한 줄이기 때문입니다. 앤트로픽 프롬프트 안내서도 값을 박아 넣지 말고, 테스트가 틀렸다면 우회하지 말고 알려 달라는 예시 지시를 싣고 있습니다.

소유권은 여러 에이전트를 함께 돌릴 때 가장 중요한 항목입니다. 수정할 수 있는 파일, 읽기만 할 파일, 아예 열지 않을 파일을 나눠 적습니다. 여러 명세를 나란히 놓았을 때 수정 가능한 파일이 겹치지 않는지 확인하면 합칠 때의 충돌을 미리 막습니다. 나누는 기준은 멀티 에이전트 작업 설계에서 다뤘습니다.

✅ 완료 증거: 다시 실행할 수 있는 형태로

완료 증거는 명세의 다섯 항목 가운데 가장 자주 비는 칸입니다. 클로드 코드 모범 사례 문서는 테스트나 빌드, 비교할 화면 캡처처럼 에이전트가 돌려 볼 수 있는 확인 수단을 주라고 권하며, 이것이 지켜보는 세션과 맡겨 두고 떠날 수 있는 세션의 차이를 만든다고 설명합니다. 확인 수단이 없으면 에이전트는 끝나 보일 때 멈추고, 사람이 확인 과정을 떠맡게 된다는 설명도 덧붙였습니다.

완료 증거는 세 부분으로 적습니다.

돌릴 명령: npm test, npm run build, 특정 스크립트처럼 받는 쪽이 똑같이 다시 돌릴 수 있는 명령
기대 결과: 실패 0건, 오류 없이 종료, 화면에 특정 문구 표시처럼 판정 기준
보고할 자료: 바꾼 파일 목록, 명령 출력의 마지막 몇 줄, 확인하지 못한 점

마지막의 확인하지 못한 점이 쓸모가 큽니다. 할 수 없었던 일이나 명세와 다르게 판단한 곳을 따로 적게 하면, 보고가 "전부 통과했습니다" 한 줄로 끝나는 것을 막을 수 있습니다.

📄 명세 한 장의 예시

가상의 예시입니다. 이 정도 길이면 한 작업의 명세로 충분합니다.

## 작업: 로그인 실패 응답 지연 제거

대상: 저장소 blog-app, 브랜치 fix/login-timeout 에서 시작
      src/lib/auth.ts 의 login() 함수

변경: 비밀번호가 틀렸을 때 5초 대기 없이 바로
      { ok: false, reason: "invalid_password" } 를 돌려준다.

제약: - 새 라이브러리를 설치하지 않는다
      - 기존 테스트를 고치거나 지우지 않는다. 테스트가 명세와
        모순되면 통과시키지 말고 무엇이 모순인지 보고한다
      - 비밀번호를 로그에 남기지 않는다

소유권: 수정 가능 src/lib/auth.ts, src/lib/auth.test.ts
        읽기만 src/app/login/ 아래 전부
        열지 않음 .env, 배포 설정

완료 증거: - npm test 실패 0건
           - 바꾼 파일 목록과 테스트 출력 마지막 20줄
           - 확인하지 못한 점이 있으면 따로 한 단락

이 명세를 받은 에이전트는 어디서 시작해 무엇을 바꾸고 어디서 멈출지를 스스로 판단할 필요가 없습니다. 결과를 받은 쪽도 명령을 한 번 다시 돌리고 바뀐 파일이 소유권 안에 있는지만 보면 합칠지 돌려보낼지가 정해집니다. 이 판정을 누가 어떤 순서로 하는지는 검수 체계에서 다룹니다.

⚠️ 명세를 쓸 때 자주 하는 실수

완료 증거를 인상으로 적습니다: "잘 동작하면", "깔끔하면"은 판정할 수 없습니다
소유권을 적지 않습니다: 에이전트가 친절하게 주변 파일까지 정리해 다른 작업과 충돌합니다
명세 하나에 작업 여럿을 넣습니다: 변경 항목이 한 문장으로 써지지 않으면 쪼갤 신호입니다
배경 설명으로 채웁니다: 왜 이 작업을 하는지는 한두 줄이면 충분합니다. 긴 배경은 에이전트가 판단할 거리를 늘릴 뿐입니다
실패했을 때 할 일을 적지 않습니다: 모순을 발견하거나 막혔을 때 멈추고 보고하라는 문장이 없으면 에이전트가 우회로를 찾습니다

❓ 자주 묻는 질문

작은 작업에도 다섯 항목을 다 써야 하나요?

변경 내역을 한 문장으로 설명할 수 있는 작은 작업이라면 대상과 변경, 완료 증거 세 줄이면 됩니다. 소유권과 제약은 여러 에이전트가 함께 일하거나 되돌리기 어려운 파일이 가까이 있을 때 반드시 적습니다.

명세는 사람이 쓰나요, 에이전트가 쓰나요?

둘 다 가능합니다. 메인 에이전트가 전체 목표를 쪼개 작업자용 명세를 쓰게 하고, 사람은 소유권이 겹치지 않는지와 완료 증거가 다시 실행할 수 있는 형태인지만 확인하는 방식이 흔합니다. 앤트로픽 리서치 시스템도 메인 에이전트에게 위임하는 법을 가르쳐 작업자용 지시를 쓰게 했습니다.

명세와 지침 파일은 무엇이 다른가요?

AGENTS.md나 CLAUDE.md 같은 지침 파일은 모든 작업에 늘 적용되는 규칙이고, 작업 명세는 이번 작업 하나에만 적용되는 지시입니다. 매번 명세에 반복해 적는 제약이 생기면 그 문장은 지침 파일로 옮기는 편이 명세를 짧게 유지합니다.

📋 3줄 요약

작업 명세는 코딩 에이전트에게 일을 맡길 때 대상과 변경, 제약, 소유권, 완료 증거 다섯 항목을 적은 지시서이고 결과를 받았을 때 합칠지 돌려보낼지를 바로 판정하게 해 줍니다.
앤트로픽은 작업자마다 목표와 결과 형식, 쓸 도구와 자료, 분명한 작업 경계를 주지 않으면 에이전트가 같은 일을 겹쳐 하거나 빈틈을 남긴다고 밝혔습니다.
완료 증거는 끝나 보인다는 인상이 아니라 다시 실행할 수 있는 명령과 기대 결과, 보고할 자료로 적어야 하고 소유권에는 만져도 되는 파일과 만지면 안 되는 파일을 함께 적습니다.

📚 참고 자료

앤트로픽, How we built our multi-agent research system: https://www.anthropic.com/engineering/multi-agent-research-system
클로드 코드 문서, Best practices: https://code.claude.com/docs/en/best-practices
앤트로픽 개발자 문서, Prompting best practices: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices
앤트로픽, The AI-native SDLC playbook: https://claude.com/blog/the-ai-native-sdlc-playbook

제대로 이해했는지 한 문제로 확인해 볼까요?

답을 고르면 바로 풀이가 나와요.

작업 명세의 완료 증거 항목을 다음 가운데 무엇으로 적는 편이 가장 알맞을까요?

4개념 / 클래스코딩 에이전트 검수 체계: 자체 검수, 기계 검사, 별도 검수자 나누기