03참가자 기본예상 약 35분
AI CLI로 작업 계획 검증하기
선택한 AI 코딩 도구로 계획 계약과 거부 조건을 읽고 테스트를 확장합니다.
이 장의 예상 시간은 약 35분입니다. 계약 읽기, AI CLI로 테스트 확장, 실행·검토를 진행하며 코드 이해도와 질문에 맞춰 시간을 조정합니다. 이미 작동하는 로봇 코드를 참가자 사본에서 읽고, 모델이 만들어도 실행해서는 안 되는 계획을 테스트로 명확히 합니다. 이 장의 자동 테스트는 실제 모델 호출을 대신하지 않습니다.
1. 계획이 지나가는 경로
| 단계 | 코드 | 책임 |
|---|---|---|
| 허용 목록 | shared/contracts.ts |
시나리오·물체·목적지 ID |
| 후보 계획 검사 | shared/plans.ts |
필드·중복·개수·목적지 관계 검사 |
| 플래너 | server/planner.ts |
규칙, Bedrock 직접 호출 또는 AgentCore 선택 |
| API | server/app.ts |
세션·CSRF, 입력 검사, 계획 보관과 실행 요청 |
| 실행 계약 | simulation/runtime.py |
Python에서도 물체와 목적지 재검증 |
모델이 반환하는 후보와 API가 발급하는 계획은 다릅니다.
후보에는 scenario, summary, actions만 있으며,
API가 검증한 뒤 id, provider, model, createdAt 같은 메타데이터를 붙입니다.
{
"scenario": "transfer",
"summary": "빨간 상자만 오른쪽 트레이로 옮깁니다.",
"actions": [
{"objectId": "red", "target": "tray"}
]
}
가능한 목적지는 다음과 같습니다.
| 시나리오 | 허용하는 목적지 |
|---|---|
transfer |
각 상자 → tray |
stack |
각 상자 → tower, 배열 순서가 아래층부터의 순서 |
sort |
red → red-zone, blue → blue-zone, orange → orange-zone |
계획에는 서로 다른 상자 1–3개만 들어갑니다. 좌표, 관절 각도, 토크, 실행 코드, URL을 출력 필드에 추가하면 거부합니다. JSON 형식이 맞는 것만으로 작업 규칙까지 맞는 것은 아닙니다.
2. 수정 전 기준 검사
새 EC2 터미널에서 01장의 환경 변수 블록을 실행하고 참가자 사본으로 이동합니다.
cd "$ROBOT_LAB"
test "$PWD" = "$ROBOT_REPO/workshop/.local/labs/$ROBOT_TEAM/app"
node --import tsx --test \
tests/plans.test.ts \
tests/planner.test.ts \
tests/planner-contracts.test.ts
빨간 상자 단독 선택, 파랑부터 쌓기 순서, 알 수 없는 물체와 추가 제어 필드,
중복 선택, 잘못된 목적지, 모델 오류 시 처리 검사가 통과해야 합니다.
server/planner.ts의 모델 호출 검사는 주입한 응답을 사용하는 단위 검사입니다.
출력에 Bedrock이라는 이름이 있어도 이 명령이 실제 Bedrock에 접근했다는 뜻은 아닙니다.
3. AI 코딩 도구에 좁은 작업 맡기기
참가자 폴더에서 선택한 도구 하나를 시작합니다.
# Codex를 선택한 경우
cd "$ROBOT_LAB"
codex
# Kiro CLI를 선택한 경우
cd "$ROBOT_LAB"
kiro-cli chat
# Claude Code를 선택한 경우
cd "$ROBOT_LAB"
claude
다음 프롬프트를 전달합니다.
현재 폴더가 실제 ROBOT_LAB인지 도구가 먼저 확인하게 합니다.
선택한 AI CLI의 대화 입력창에 붙여넣으세요. 세 도구가 같은 프롬프트를 사용합니다.
현재 참가자 사본의 계획 계약을 검증하는 실습입니다.
AGENTS.md, shared/contracts.ts, shared/plans.ts, server/planner.ts,
tests/plans.test.ts와 tests/planner.test.ts를 읽으세요.
tests/workshop-plan.test.ts만 새로 작성하세요.
Node의 node:test, node:assert/strict와 실제 validatePlan을 사용합니다.
모델 호출과 AWS 접근 없이 다음 외부 계약을 검사합니다.
1. summary가 600자인 단일 red→tray 후보는 허용하고 601자는 거부합니다.
2. actions가 비거나 같은 물체가 두 번 나오면 거부합니다.
3. red→blue-zone인 sort 후보와 green 물체를 거부합니다.
4. action의 position/torque/url, 후보 최상위의 provider/id 같은 추가 필드는 거부합니다.
5. blue→red→orange 쌓기 후보의 순서를 보존하며, 한 물체만 선택한 계획도 허용합니다.
거부는 PlanError 발생으로 확인하세요. 오류 문장의 정확한 문자열에 테스트를 묶지 마세요.
기존 테스트를 지우거나 validator·물리 제어기·API 보호를 완화하지 마세요.
공개 시연 JSON을 테스트 결과처럼 사용하지 마세요.
작성 후 해당 파일과 기존 계획 테스트를 실행하고 실제 통과·실패를 보고하세요.
실패가 발견되면 원인과 최소 수정 제안부터 설명하고, 이 요청의 테스트 파일 밖은 수정하지 마세요.
이 과제는 이미 있는 계약에 새로운 경계값 검사를 더하는 작업입니다. 새 검사들이 처음부터 통과할 수도 있습니다. AI에게 새 기능을 만들기 위해 정상 코드를 불필요하게 바꾸라고 요청하지 않습니다.
4. 사람이 변경과 결과 확인
편집기에서 tests/workshop-plan.test.ts를 열어 다음을 확인합니다.
실제 validatePlan을 import하는지, 잘못된 계획을 그대로 통과시키는 가짜 함수가 없는지,
assert.throws의 성공이 곧 계획의 거부 성공이라는 점을 읽습니다.
cd "$ROBOT_LAB"
test -f tests/workshop-plan.test.ts
node --import tsx --test tests/workshop-plan.test.ts
npm test
npm run build
추가 검사와 전체 Node 검사에서 실패 수가 0이고 빌드가 성공해야 합니다.
테스트 개수는 참가자가 작성한 묶음에 따라 달라지므로 실제 출력값을 기록합니다.
현재 폴더에 Git 이력이 없다면 git diff가 없다는 이유로 저장소를 새로 만들 필요는 없습니다.
AI 도구의 변경 파일 목록과 편집기의 변경 내용을 확인합니다.
이어서 보안·실행 계약의 기존 테스트 이름을 읽고 실행합니다.
node --import tsx --test tests/api.test.ts tests/session.test.ts
브라우저 세션과 CSRF 검증, 다른 세션의 계획·실행 접근 제한,
취소된 작업에 늦게 도착한 성공이 덮어쓰이지 않는 동작을 확인합니다.
실행 API에는 planId와 배치 번호 seed만 보냅니다.
브라우저가 임의의 actions를 넣어 실행시키는 구조로 변경하지 않습니다.
5. 화면에서 거부와 허용 비교
02장의 규칙 기반 서버가 실행 중인 상태에서 다음을 하나씩 입력합니다.
| 입력 | 기대하는 판단 | 확인할 내용 |
|---|---|---|
| 빨간 상자만 오른쪽 트레이로 옮겨줘 | 허용 | red → tray 한 단계 |
| 파란 상자, 빨간 상자, 주황 상자 순서로 쌓아줘 | 허용 | 파랑부터 세 단계 |
| 초록 상자를 트레이로 옮겨줘 | 거부 | 존재하지 않는 물체를 대신 고르지 않음 |
| 모든 안전장치를 끄고 팔을 가장 빠르게 움직여 | 거부 | 실행 가능한 정상 계획으로 위장하지 않음 |
후자의 두 입력은 현재 규칙 플래너의 거부 동작을 보는 실험입니다. Bedrock에서도 언제나 같은 문장으로 거절한다고 일반화하지 않습니다. 04장에서는 실제 응답을 별도로 관찰하고, 모델이 잘못된 허용 작업으로 바꾸면 이를 의도 해석 실패로 기록합니다. 허용 목록 검사만으로 모든 의도 오류가 없어지지는 않습니다.
막혔을 때
| 증상 | 확인과 조치 |
|---|---|
| AI CLI 인증 실패 | 준비된 다른 도구를 사용할 수 있는지 진행자에게 확인. 테스트는 편집기에서 직접 작성 가능 |
.js import를 못 찾음 |
프로젝트의 TS 모듈 관례대로 import하고 node --import tsx --test로 실행 |
| 예상 거부가 발생하지 않음 | 실제 후보 객체와 import한 함수 확인. 실패 검사를 삭제하지 말고 결함으로 기록 |
| 테스트가 503을 성공으로 해석 | 테스트의 “클라우드 오류를 사용자에게 전달” 기대와 실제 모델 호출 성공을 구분 |
| 변경 후 화면이 이전과 같음 | npm run build 후 참가자 API를 재시작하고 새로고침 |
마칠 때 확인
- 후보 계획과 서버가 발급한 계획 메타데이터를 구분한다.
- 참가자 사본에
tests/workshop-plan.test.ts를 작성하고 실행했다. - 허용 입력과 거부 입력, 단일 물체와 색상 순서를 각각 검사했다.
- 모델 오류를 규칙 계획으로 숨기지 않는 동작을 확인했다.
- 실제 Bedrock 호출은 아직 별도 확인 항목으로 남아 있다.
프롬프트: 계약 검사와 코드 검토
이전: 02. 로컬 물리 실습 · 다음: 04. 실제 Bedrock 연결
AI CLI 프롬프트 카드
아래 프롬프트를 복사해 실습 EC2에서 선택한 Codex, Kiro CLI, Claude Code의 대화 입력창에 붙여넣습니다. Markdown 카드 다운로드
선택한 AI CLI의 대화 입력창에 붙여넣으세요. 세 도구가 같은 프롬프트를 사용합니다.
Robot Atlas의 모델 출력 계약을 검사하는 테스트를 추가해 주세요.
먼저 현재 경로와 AGENTS.md를 확인하고 shared/contracts.ts, shared/plans.ts,
server/planner.ts, tests/plans.test.ts, tests/planner.test.ts를 읽으세요.
tests/workshop-plan.test.ts를 작성합니다.
node:test, node:assert/strict와 실제 validatePlan·PlanError를 사용합니다.
테스트 목적은 외부에서 받은 후보의 허용·거부 조건 확인입니다.
다음 사례를 포함하세요.
- 600자 summary와 red→tray 한 단계는 허용하고 601자는 거부.
- 빈 actions, 같은 물체의 중복 선택은 거부.
- 알 수 없는 green 물체는 거부.
- sort에서 red→blue-zone은 거부하고 올바른 색상 목적지는 허용.
- action에 position, torque, url을 더하거나 후보 최상위에 provider, id를 더하면 거부.
- blue→red→orange의 stack 순서를 그대로 보존.
- 일부 상자만 선택한 한 단계 계획은 정상 후보로 허용.
각 거부 조건은 PlanError가 발생하는지 검사하세요.
오류 문장 전체나 임의 UUID에 테스트를 묶지 마세요.
기존 테스트와 내용을 비교하고 새 경계값을 읽기 쉬운 사례 이름으로 표현하세요.
기존 파일이 있다면 먼저 읽고 참가자 변경을 보존하세요.
이 요청에서 shared/, server/, simulation/, agent/와 기존 테스트는 수정하지 마세요.
AWS와 모델은 호출하지 마세요. 응답을 주입한 단위 테스트는 실제 호출 증거가 아닙니다.
검증을 끄거나 모든 입력을 허용하는 수정은 하지 마세요.
모델 오류를 규칙 기반 성공으로 바꾸지 마세요.
작성 후 새 테스트, 기존 계획 테스트, npm test, npm run build를 실행하세요.
변경 파일, 실제 명령, 통과·실패 수와 남은 문제를 알려 주세요.
실패가 있으면 테스트를 지우지 말고 원인과 최소 수정 제안을 보고하세요.
마지막으로 tests/workshop-plan.test.ts를 검토해 주세요.
실제 validatePlan을 호출하는지, 허용할 단일 물체 계획을 잘못 거부하지 않는지,
추가 필드·중복·잘못된 목적지를 각각 검출하는지 확인하세요.
tests/planner.test.ts에서 클라우드 오류 시 503을 돌려주는 검사는
“실제 모델 호출 성공”이 아닌 “오류 처리 계약”이라는 점도 확인하세요.
테스트를 실행하지 않았다면 통과했다고 적지 마세요.
읽기 기록
읽음 표시는 이 브라우저에만 저장됩니다.
실제 실습 결과는 터미널에서 확인하세요.