목표와 루브릭

목표와 루브릭 (Goals and Rubrics)

에이전트에게 일을 시킬 때 "대략 이렇게 해줘"보다는 "이 정도 조건이 만족되면 끝났다고 판단해줘"가 필요할 때가 있어요. Deep Agents Code는 이 판단을 돕기 위해 **목표(goal)**와 루브릭(rubric) 두 가지를 제공해요. 목표는 측정 가능한 목적을 세우고 에이전트가 완료 기준을 스스로 제안하게 하는 방식이고, 루브릭은 이미 정해 둔 기준을 그대로 채점에 쓰는 방식이에요. 여기서 둘의 차이와 사용법을 살펴볼게요.

출처: 공식문서

목표와 루브릭 고르기

**목표(goal)**는 측정 가능한 목적이 하나 있고, 작업을 시작하기 전에 Deep Agents Code가 완료 기준(acceptance criteria)을 먼저 작성해 주길 원할 때 써요. 목표에는 생명주기가 있어요. 일단 수락되면 턴을 넘나들며 활성 상태로 유지되다가, 일시정지하거나, 에이전트가 완료·차단으로 표시하거나, 직접 지우기 전까지 계속돼요. 진행 중인 목표를 작업을 다시 시작하지 않고 수정할 수도 있어요.

**루브릭(rubric)**은 에이전트가 채점되길 원하는 기준을 이미 알고 있을 때 써요. 루브릭은 다음 턴에만 적용되거나 이후 턴에도 지속될 수 있어요.

흔한 패턴을 정리하면 이래요:

  • 목적 하나, 에이전트가 기준 작성: /goal <objective> 사용
  • 모든 턴에 지속되는 기준: /rubric set <criteria> 사용
  • 파일에 저장된 기준: /rubric file <path> 사용
  • 한 턴용 품질 게이트: /rubric next <criteria> 사용

목표 사용하기 (Use a goal)

원하는 결과는 알지만, 작업을 시작하기 전에 완료 기준을 Deep Agents Code가 제안하길 원할 때 /goal을 써요. 목표는 개방형 작업에 유용해요. 에이전트가 목적을 구체적인 "definition of done"으로 바꾸고, 그 기준이 만족될 때까지 반복하기 때문이에요.

/goal add OAuth refresh handling

Deep Agents Code는 작업을 시작하기 전에 검토용 완료 기준을 작성해요.

작성된 기준이 어떻게 처리되는지는 승인 모드에 따라 달라져요:

  • Manual: 항상 인라인 검토를 엽니다.
  • Auto: 기본적으로 검토를 엽니다. ~/.deepagents/config.toml에서 goals.auto_accept_criteria = true로 설정하면 생성된 기준을 자동 적용합니다.
  • YOLO: 검토 없이 생성된 기준을 적용합니다.

기준이 수락된 후에는, 목표가 일시정지·완료·차단·해제될 때까지 턴을 넘나들며 활성 상태로 유지돼요.

이 방식 덕분에 여러 턴에 걸쳐 더 큰 목적을 향해 작업할 수 있어요:

/goal migrate auth callbacks to the new API
start with the OAuth callback
now update the tests
check the docs too

입력창 위의 목표 패널에는 현재 목적과 그것이 활성·일시정지·차단·완료 중 어느 상태인지 표시돼요. /goal show로 현재 목표를 확인하고, /goal clear로 제거할 수 있어요.

목표 수정·일시정지·재개 (Amend, pause, and resume a goal)

현재 작업을 취소하고 다시 시작하지 않고도 진행 중인 목표를 조종할 수 있어요.

  • /goal amend <feedback> — 목적과 기준에 대한 조정안을 제안해요. 수정도 같은 인라인 검토(수락, 편집, 재고, 취소)를 거쳐 확정돼요.
  • /goal pause — 작업이나 채점을 주도하지 않도록 목표를 저장만 해요. 그 사이의 프롬프트는 목표 없이 실행돼요. /goal resume은 저장된 목표를 다시 활성화하고 기존 대화에서 이어가요.
/goal amend remove JSON export, add streaming CSV support, keep the CSV tests
/goal pause
/goal resume

완료와 채점 (Completion and grading)

작업이 끝날 때까지, 각 후속 턴은 목표의 완료 기준에 맞춰 채점돼요.

  • 목표의 완료가 승인되면 Deep Agents Code가 목표를 지워요

목표 명령 참조

  • /goal <objective>: 일반 언어 목적에서 완료 기준을 작성하고 작업 시작 전에 검토하기
  • /goal amend <feedback>: 검토를 위해 목적과 기준 조정안 제안하기
  • /goal pause: 작업이나 채점을 주도하지 않도록 목표 저장하기
  • /goal resume: 일시정지된 목표를 다시 활성화하고 기존 대화에서 이어가기
  • /goal show: 현재 목표, 상태, 기준 확인하기
  • /goal clear: 활성 목표 제거하기
  • /goal model [provider:model|clear]: 목표를 채점할 모델 설정·해제하기
  • /goal max-iterations <N|clear>: 목표의 최대 채점 반복 횟수 설정·해제하기

루브릭 사용하기 (Use a rubric)

완료 기준을 이미 알고 있고, 그것을 에이전트 작업의 품질 게이트로 삼고 싶을 때 /rubric을 써요.

/rubric set tests pass; no unrelated files changed; help text is updated
/rubric next only change the auth callback; do not refactor unrelated code
/rubric file acceptance.md

sticky 루브릭은 지우기 전까지 이후 턴에도 적용돼요. next-turn 루브릭은 다음에 제출하는 작업에만 적용돼요.

루브릭 명령 참조

  • /rubric show: 활성 루브릭 확인하기
  • /rubric clear: 활성 루브릭 제거하기
  • /rubric model <provider:model>: 루브릭 결과를 채점할 모델 설정하기

비대화형 모드에서 루브릭 사용하기

비대화형 실행은 목표 검토를 위해 멈출 수 없어요. 기준을 이미 알고 있는 작업에는 --rubric을 써요:

dcode -n "implement OAuth refresh handling" --rubric "tests pass; no unrelated files changed"
dcode -n "implement OAuth refresh handling" --rubric @acceptance.md

채점 모델과 최대 채점 반복 횟수도 설정할 수 있어요:

dcode -n "implement OAuth refresh handling" \
  --rubric "tests pass; no unrelated files changed" \
  --rubric-model openai:gpt-5.5 \
  --rubric-max-iterations 3

더 알아보기 (Learn more)