Claude Code나 Codex 같은 AI 에이전트를 쓰다 보면 터미널 앞에 앉아 한 턴씩 대화하며 일을 시키게 되죠. 이 글에서는 대화 대신 목표만 주면 에이전트가 알아서 일하는 AI 에이전트 자동화 사례 4가지와, 그 사례들에서 공통으로 보이는 방법을 정리했어요.
먼저 고백할 게 있어요. 저도 2026년 3월에 "아이디어 파일을 던져두면 PM 에이전트가 태스크로 쪼개고 개발 에이전트가 실행하는" 파이프라인을 설계했어요. 그런데 이 설계는 실제로 동작하지 않았어요. 그래서 이번에는 제 설계 대신, 지금 실제로 돌아가고 공개 문서로 확인할 수 있는 사례만 골랐어요.
대화로 일 시키기와 목표로 일 시키기#
터미널에서 대화로 일을 시키면 사람이 계속 그 자리에 있어야 해요. 에이전트가 한 단계를 끝낼 때마다 다음 지시를 주고, 결과를 확인하고, 다시 지시하는 식이거든요.
목표로 일을 시키는 방식은 순서가 반대예요. 사람은 무엇을 원하는지와 언제 끝난 건지를 이슈나 파일로 남기고 자리를 떠요. 에이전트는 그 문서를 읽고 일하다가, 결과를 PR이나 기록으로 돌려줘요.
| 구분 | 터미널 대화 | 목표 맡기기 |
|---|---|---|
| 사람이 주는 것 | 단계별 지시 | 목표, 제약, 완료 조건 |
| 일이 시작되는 때 | 사람이 입력할 때 | 이슈 할당, 정해진 시간, 루프 |
| 사람이 보는 때 | 매 턴 | PR 리뷰, 실행 기록 |
사례 1: 이슈를 할당하면 PR이 돌아와요#
가장 쉽게 시작할 수 있는 건 GitHub 이슈를 에이전트에게 맡기는 방식이에요. 동료에게 이슈를 넘기듯 에이전트에게 넘기면, 에이전트가 브랜치를 만들어 작업하고 PR로 결과를 가져와요.
GitHub Copilot에게 이슈 할당하기#
GitHub Copilot은 이슈의 Assignees에서 Copilot을 고르면 일을 시작해요. 공식 문서에 따르면 Copilot은 작업을 시작하고, PR을 올린 뒤, 끝나면 사람에게 리뷰를 요청해요. 수정이 필요하면 PR 댓글에 @copilot을 멘션하면 돼요.
문서에서 눈여겨볼 주의사항이 하나 있어요. 할당한 뒤에 이슈에 단 댓글은 Copilot이 보지 못해요. 그래서 이슈를 할당하기 전에 원하는 결과, 사용할 패턴, 테스트 요구사항, 건드리면 안 되는 파일까지 이슈 본문에 다 적어둬야 해요. 또 기본 설정에서는 Copilot이 PR에 푸시해도 GitHub Actions 워크플로가 바로 돌지 않아요. 사람이 변경 내용을 보고 Approve and run workflows를 눌러야 실행돼요.
Claude Code GitHub Actions로 @claude 부르기#
Claude Code GitHub Actions는 저장소의 워크플로 안에서 Claude Code를 실행해요. 이슈나 PR 댓글에 @claude를 멘션하면 Claude가 코드를 분석하고, 변경을 구현하고, 커밋을 푸시해요. 설정은 Claude Code에서 /install-github-app을 실행하면 앱 설치, 시크릿 등록, 워크플로 PR 생성까지 안내해줘요.
@claude implement this feature based on the issue description
@claude fix the TypeError in the user dashboard component저장소 루트에 CLAUDE.md를 두면 Claude가 PR을 만들 때 그 안의 코드 스타일과 규칙을 따라요. 매번 대화로 설명하던 규칙을 파일 하나로 옮겨두는 셈이에요.
사례 2: 정해진 시간에 스스로 일을 시작해요#
이슈 할당도 결국 사람이 "지금 해"라고 누르는 거예요. 반복되는 일이라면 트리거 자체를 일정에 맡길 수 있어요.
Claude Code GitHub Actions의 예약 실행#
Claude Code GitHub Actions는 워크플로에 prompt를 넣으면 멘션을 기다리지 않는 자동화 모드로 돌아요. cron 일정과 묶으면 매일 정해진 시간에 같은 목표로 일을 시작해요. 아래는 공식 문서의 예시로, 매일 09:00(UTC)에 전날 커밋과 열린 이슈를 요약해요.
name: Daily Report
on:
schedule:
- cron: '0 9 * * *' # 매일 09:00 UTC
jobs:
report:
runs-on: ubuntu-latest
permissions:
contents: read
issues: read
id-token: write
steps:
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
# 이 문장이 에이전트에게 주는 목표예요
prompt: "Generate a summary of yesterday's commits and open issues"
# 목표에 필요한 도구만 허용해요
claude_args: |
--allowedTools "mcp__github__list_commits,mcp__github__list_issues"prompt만 주면 Claude는 셸이나 GitHub API를 쓸 수 없어요. 목표에 필요한 도구를 --allowedTools로 직접 열어줘야 해요. 비용을 줄이려면 --max-turns로 반복 횟수를 제한하고, 워크플로에 타임아웃을 거는 게 좋다고 문서에 적혀 있어요.
Multica Autopilots의 Runbook#
제가 지금 에이전트 작업 관리에 쓰는 Multica에도 같은 역할을 하는 Autopilots가 있어요. Autopilot 하나에는 목표, 배경, 제약, 단계를 적은 Runbook과 담당 에이전트, 트리거가 들어가요.
트리거는 정해진 일정(schedule), 외부 시스템이 보내는 웹훅(webhook), 수동 실행 세 가지예요. 트리거가 걸리면 이슈를 만들어 에이전트에게 할당하거나, 이슈 없이 에이전트를 바로 실행해요. 문서의 예시는 매주 월요일 09:00 고객 피드백 정리, 매일 진행 상황 요약, 주기적인 의존성 점검 같은 일이에요.
사례 3: Ralph 루프, 목표 파일을 계속 먹여요#
Ralph는 Geoffrey Huntley가 2025년 7월에 소개한 방식이에요. 핵심은 정말 한 줄짜리 Bash 루프예요.
# 같은 목표 파일을 에이전트에게 끝없이 다시 넣어요
while :; do cat PROMPT.md | claude-code ; done루프가 돌 때마다 에이전트는 새 컨텍스트로 시작해요. 그래서 기억은 대화가 아니라 파일에 남겨요. 대화로 먼저 만들어둔 스펙(specs 폴더, 파일 하나에 스펙 하나), 우선순위가 매겨진 할 일 목록 fix_plan.md, 빌드 방법을 적은 AGENT.md를 매 루프 같은 방식으로 읽어요.
Huntley가 강조하는 규칙은 이래요.
- 한 루프에 하나만 — 할 일 목록에서 가장 중요한 항목 하나만 처리해요.
- 백프레셔(backpressure) — 테스트, 정적 분석, 타입 체크로 잘못된 결과를 튕겨내요.
- 진행은 git으로 — 끝난 작업은 커밋하고, 빌드와 테스트가 통과하면 태그를 달아요.
- 틀리면 프롬프트를 고쳐요 — 에이전트가 같은 실수를 반복하면 도구를 탓하기보다 프롬프트에 "표지판"을 추가해요.
다만 Huntley 본인도 Ralph는 새 프로젝트(greenfield)에 가장 잘 맞고, 기존 코드베이스에는 쓰지 않겠다고 했어요. 엔지니어가 더는 필요 없다는 주장에도 선을 그었어요.
사례 4: 몇 시간짜리 작업은 하네스로 이어가요#
Anthropic은 2025년 11월 엔지니어링 블로그에 장기 실행 에이전트를 위한 하네스(harness)를 공개했어요. 상위 수준의 프롬프트 하나로 웹 앱을 끝까지 만들게 하려고 했더니, 에이전트가 두 가지 방식으로 실패했다고 해요.
- 한 번에 너무 많이 만들다가 컨텍스트가 바닥나서, 기능을 반쯤 만든 채로 기록도 없이 끝났어요.
- 다음 세션의 에이전트가 이미 만들어진 걸 보고 프로젝트가 끝났다고 선언했어요.
해법은 에이전트를 두 역할로 나누는 거였어요.
- 초기화 에이전트(initializer agent) — 첫 세션에서만 돌아요. 개발 서버를 띄우는
init.sh, 작업 기록 파일claude-progress.txt, 첫 git 커밋을 만들어요. 그리고 스펙을 바탕으로 기능 목록을 JSON으로 써요. - 코딩 에이전트(coding agent) — 이후 모든 세션에서 돌아요. 기록 파일과 git 로그를 읽고, 아직 통과하지 못한 기능 중 우선순위가 가장 높은 것 하나만 구현해요.
기능 목록의 항목은 이런 모양이에요. claude.ai 클론 예시에서는 이런 항목이 200개가 넘었고, 처음에는 전부 passes: false로 시작해요.
{
"category": "functional",
"description": "기능 설명",
"steps": ["검증 단계 1", "검증 단계 2"],
"passes": false
}코딩 에이전트는 passes 값만 바꿀 수 있어요. 글에 따르면 JSON을 고른 이유는 마크다운보다 모델이 함부로 고칠 가능성이 낮아서였어요. 또 에이전트가 유닛 테스트나 curl만 보고 완료 처리하는 일이 많았는데, 브라우저 자동화로 사람처럼 직접 써보며 검증하라고 지시하자 결과가 크게 좋아졌다고 해요.
실제로 돌아가는 사례의 공통점#
네 사례를 나란히 놓으면 목표를 맡기는 방법이 몇 가지로 모여요.
- 목표는 한 곳에 완결해서 적어요 — 이슈 본문,
prompt, Runbook,PROMPT.md처럼요. 맡긴 뒤에 덧붙이는 말은 전달되지 않을 수 있어요. - 한 번에 하나만 시켜요 — Ralph는 한 루프에 한 항목, Anthropic 하네스는 한 세션에 기능 하나예요.
- 기억은 대화가 아니라 파일과 git에 남겨요 — 할 일 목록, 진행 기록, 커밋이 다음 실행의 출발점이 돼요.
- 끝났는지는 에이전트 말이 아니라 검증으로 판단해요 — 테스트, 타입 체크,
passes플래그, 브라우저 검증 같은 장치가 있어요. - 사람은 결과를 리뷰하는 자리에 있어요 — PR 리뷰 요청, 실행 기록, 워크플로 승인처럼 사람이 확인하는 지점이 남아 있어요.
제 Idea-to-Task 설계가 동작하지 않은 이유#
제 3월 설계는 docs/ideas/에 아이디어를 쓰면 PM 에이전트가 이를 감시하다가 docs/tasks/에 태스크 파일을 만들고, 할당 엔진이 개발 에이전트에게 나눠주는 구조였어요. 비슷한 마크다운 자동화를 직접 만들어 굴려봤을 때, 사람이 노트만 쓰면 끝나는 그림은 나오지 않았어요. 결과 품질, 관리 부담, 파이프라인 유지보수 문제는 마크다운으로 AI 에이전트 작업 자동화할 때 챙길 것에 정리해두었어요.
위 사례들과 비교하면 차이가 보여요. 사례들은 GitHub 이슈, Actions, git처럼 이미 있는 도구 위에 얹었고, 끝났는지를 판단하는 장치가 분명해요. 제 설계는 폴더 감시, PM 에이전트, 할당 엔진을 새로 만들어야 했어요. 태스크 파일에도 무엇을 만들지만 있고, 끝났는지 판단할 완료 조건이나 검증 방법은 적혀 있지 않았어요.
작게 시작하는 방법#
처음부터 파이프라인을 만들 필요는 없어요. 지금 저장소 하나에 Claude Code GitHub Actions나 Copilot을 연결하고, 터미널에서 대화로 설명하던 내용을 완료 조건까지 적은 이슈 하나로 옮겨서 맡겨보세요. 이슈를 지시서로 잘 쓰는 법은 Obsidian 노트를 AI 에이전트 작업 지시서로 쓰기의 목표, 맥락, 완료 조건, 하지 말 것 구조를 그대로 쓰면 돼요.
Be a good listener. Your ears will never get you in trouble.
— Frank Tyger
