에이전트가 일하는 동안 리뷰하세요

10시 40분, 청구 서비스에서 관리형 실행을 시작합니다. 작업은 "서비스를 로컬에서 설정하고 실행하는 방법을 문서로 정리하기"입니다. 11시 02분, 새 docs/setup.md가 담긴 pull request가 도착합니다. 괜찮은 수준입니다. 그런데 12번째 줄은 새로 합류한 사람들에게 go build ./...를 실행하라고 안내하는데, 이 명령은 서비스에 필요한 build tag를 빠뜨립니다. 그래서 그들의 첫 빌드는 문서 어디에도 설명되지 않은 방식으로 실패합니다. 그리고 6분쯤 어딘가에서 에이전트는 README의 Docker 섹션이 오래됐다고 판단하고 다시 썼습니다. 아무도 요청하지 않은 일입니다.

어느 것도 리뷰에서 고치기 어려운 문제는 아닙니다. 리뷰가 돌려줄 수 없는 것은 그 사이의 20분입니다. 에이전트는 확인해 줄 사람 없이 이른 시점에 그런 선택을 했고, 그 뒤의 모든 작업을 그 위에 쌓았습니다. 그러면 수정은 처음부터 다시 시작해 같은 파일을 다시 읽고 두 번째 pull request를 여는 두 번째 실행이 됩니다.

지금까지 Archyl의 관리형 에이전트 실행은 이렇게 동작했습니다. 실행 페이지에는 이벤트 피드와 지시 입력란이 있어서, 탭을 열어 두면 노트북에서든 휴대폰에서든 도구 호출을 따라갈 수는 있었습니다. 하지만 에이전트가 무엇을 하려는지, 지금까지 무엇을 썼는지는 도구 호출 페이로드를 짜 맞추거나 pull request를 보고서야 알 수 있었습니다. 야간 의존성 감사라면 그걸로 충분합니다. 어차피 리뷰할 변경이라면, 리뷰가 가장 비싼 시점에 오게 됩니다.

이제 실행에 리뷰 루프가 생겼습니다. 달라진 점은 다음과 같습니다.

이 글의 나머지 부분에서는 같은 작업을 새로운 방식으로, 실제로 겪게 될 순서대로 다시 진행합니다. 작업은 예시이며, 아래에 인용한 모든 메시지는 에이전트가 실제로 받는 형식입니다.

계획이 먼저입니다

파일을 건드리기 전에 에이전트는 한 문장 요약과 몇 가지 구체적인 단계를 담아 propose_plan을 호출하라는 지시를 받습니다. 프롬프트는 3~8개의 단계를 요구하고, 도구는 12개를 넘는 단계를 거부하므로 계획은 한눈에 읽히는 분량으로 유지됩니다. 실행 페이지 상단의 계획 패널은 이를 체크리스트로 보여 줍니다. 작업을 진행하면서 에이전트는 각 단계를 진행 중, 완료 또는 건너뜀으로 표시하고 때로는 짧은 메모를 덧붙이며, 패널에는 현재 단계와 진행률(2/4)이 표시됩니다.

기본적으로 계획은 공유만 되고 에이전트는 바로 작업을 시작합니다. 에이전트 프로필의 협업에서 계획 먼저 검토를 켜면, 에이전트는 대신 당신을 기다립니다. 패널은 검토 모드로 바뀌고, 여기서 단계 이름을 바꾸고 세부 내용을 추가하며, 단계를 추가, 삭제하거나 순서를 바꿀 수 있습니다.

설정 문서를 위해 에이전트는 다섯 단계를 제안했습니다. 네 번째는 "README의 Docker 섹션 업데이트", 즉 아무도 요청하지 않은 재작성이었습니다. 이 단계를 삭제하고 2단계에 세부 내용을 추가하면, 계획 승인이었던 버튼이 수정한 계획 승인으로 바뀝니다. 에이전트가 돌려받는 내용은 다음과 같습니다.

The plan was approved with edits. Follow this plan:
1. Read the Makefile, docker-compose.yml and the config loader
2. Write prerequisites and environment variables — take values from .env.example, never from a real .env
3. Document the build, test and run commands
4. Link docs/setup.md from the README
Call update_plan when each step starts and when it is done or skipped.

당신이 수정한 버전이 에이전트가 따르는 계획이자 체크리스트가 추적하는 계획이 됩니다. 계획이 약간 어긋난 정도가 아니라 틀렸다면, 대신 변경 요청으로 피드백을 보냅니다. 에이전트는 계획을 고쳐 새 리비전을 제안하고, 이전 리비전은 피드에 남으므로 당신의 피드백이 무엇을 바꿨는지 볼 수 있습니다.

계획이 승인되기 전까지 에이전트는 파일을 쓰거나, Archyl 도구로 아키텍처 모델을 변경하거나, 커넥터를 통해 저장소에 푸시할 수 없습니다. 이것은 에이전트가 말로 둘러대며 넘어갈 수 있는 프롬프트 속 한 줄이 아닙니다. 호출 자체가 거부되고, 에이전트는 다음 메시지를 읽습니다.

changes are refused until your plan is approved: call propose_plan and wait for the review

1시간 안에 아무도 계획을 검토하지 않으면, 실행은 아무것도 변경하지 않은 채 실패합니다. 검토를 요구하는 프로필은 아무도 나타나지 않았다는 이유로 검토를 건너뛰지 않습니다.

사람이 결정해야 할 때는 질문합니다

에이전트가 혼자 내려서는 안 되는 결정이 있습니다. 모호한 요구 사항, 뚜렷한 승자가 없는 트레이드오프, 파괴적인 작업 같은 것들입니다. 이런 경우를 위해 ask_human이 있습니다. 지시 사항은 직접 찾아볼 수 있는 것은 절대 묻지 말라고 하며, 질문은 실행당 최대 5개입니다. 그래서 질문 하나씩 작업을 당신에게 되돌려 보낼 수는 없습니다.

2단계를 진행하던 중, 에이전트는 설정에서 STAGING_DATABASE_URL을 발견합니다. 문서화하면 도움이 되겠지만, staging에는 VPN 접근이 필요하고 새로 합류한 사람은 첫 주 동안 그 권한을 받지 못합니다. 저장소 어디에도 그런 내용은 없으니 에이전트는 질문합니다.

질문은 피드 위에 표시됩니다. 에이전트가 답을 제안한 경우 추천 답변("staging은 빼 주세요", "VPN 접근에 대한 메모와 함께 언급해 주세요")이 함께 나오고, 직접 답을 적는 입력란도 있습니다(Cmd/Ctrl + Enter로 전송). 프로젝트를 편집할 수 있는 사람이라면 누구나 답할 수 있으며, 누가 답했는지는 피드에 기록됩니다. 에이전트는 The human answered: Leave staging out을 읽고 작업을 이어 갑니다.

1시간 안에 아무도 답하지 않은 질문은 실행을 실패시키지 않습니다. 에이전트는 자체 판단으로 계속 진행하고, 자신이 세운 가정을 결과에 밝힙니다. 계획과는 반대인데, 그 차이는 무엇이 걸려 있느냐에 있습니다. 검토되지 않은 계획은 아무것도 합의되지 않았다는 뜻이지만, 답이 없는 질문은 에이전트가 실행 내내 내리는 종류의 결정이 하나 더 늘어나는 것일 뿐입니다.

기다림의 비용

에이전트가 계획 검토나 답변을 기다리는 동안 실행에는 응답 대기 중이 표시되고, 실행 목록은 이를 조치 필요 아래에 분류합니다. 피드 위의 배너가 무엇을 기다리는지, 즉 계획 검토를 기다리는 중인지 에이전트에게 질문이 있습니다인지 알려 주고 해당 위치로 안내합니다.

대기 시간은 실행의 시간 한도에 포함되지 않습니다. 기다린 시간만큼 마감 시각이 뒤로 밀리므로, 한도가 30분인 실행이 당신을 20분 기다렸더라도 여전히 30분 동안 작업할 수 있습니다. 다만 동시 실행 자리는 계속 차지합니다. 승인 대기 중인 실행은 아직 시작하지 않았으니 아무것도 점유하지 않지만, 대기 중인 실행은 워크스페이스를 연 채 대화 도중에 멈춰 있고, 당신의 답이 도착하면 곧바로 재개할 준비가 되어 있기 때문입니다.

쓰는 즉시 보이는 diff

실행 페이지에는 이제 두 가지 보기가 있습니다. 이벤트 피드인 활동과 변경 사항입니다. 변경 사항에는 에이전트가 쓰는 모든 파일이 쓰는 즉시 나열되며, 상태(추가됨, 수정됨 또는 차단됨)와 함께 파일별 및 실행 전체의 추가·삭제된 줄 수가 표시됩니다. 파일을 선택하면 최종 상태뿐 아니라 각 쓰기가 무엇을 바꿨는지(수정 2/3)도 볼 수 있습니다.

모든 파일 쓰기에 대한 적합성 검사이자 이제 워커 안에서 실행되는 Guard도 여기에 나타납니다. Guard가 거부한 쓰기는 차단됨으로 표시됩니다. 그 내용은 파일에 반영되지 않았지만, diff에는 에이전트가 쓰려던 내용과 위반한 규칙이 나타납니다. 경고만 받은 쓰기는 반영되고, 파일에 경고가 붙습니다. 예전에는 도구 결과 안에서 찾아야 했던 거부가, 이제는 읽을 수 있는 diff가 되었습니다.

제한은 두 가지입니다. 긴 diff는 600줄에서 잘리고, 128 KB를 넘는 파일은 diff 없이 나열됩니다.

12번째 줄에 남기는 코멘트

다시 go build ./...로 돌아가 봅시다. pull request를 기다릴 필요가 없습니다. 변경 사항에서 줄 번호를 클릭하고 코멘트를 쓴 다음 에이전트에게 보내기를 누릅니다(Cmd/Ctrl + Enter). 에이전트는 다음 단계에서 이를 파일, 줄, 그 내용이 담긴 코드 리뷰 코멘트로 받습니다.

[Review comment from a human operator on docs/setup.md, line 12 of the file as you wrote it]
> go build ./...
Use the make target instead, it sets the build tags.
Address the comment in that file, then carry on with your plan.

에이전트는 그 줄을 고친 뒤 하던 단계로 돌아갑니다. 줄 아래의 코멘트는 에이전트가 가져가기 전까지 대기 중, 그 뒤에는 전달됨으로 표시됩니다. 코멘트는 활동에도 나타나고, 목록의 각 파일에는 코멘트 수가 표시됩니다. 수정 사항은 그 파일의 다음 편집으로 도착하므로, 코멘트를 남긴 diff가 곧 수정을 확인하는 곳이 됩니다.

추가된 줄, 변경되지 않은 줄, 삭제된 줄 모두에 코멘트할 수 있습니다. 삭제된 줄에 남긴 코멘트는 "the lines you removed"에 대한 코멘트로 에이전트에게 전달되므로, 검사를 되살리라고 말할 때 쓸 수 있습니다. 코멘트는 에이전트가 작업 중이거나 당신을 기다리는 동안 받으며, 대기 중인 에이전트는 재개할 때 이를 읽습니다. 실행이 끝날 때까지 대기 중인 코멘트에는 전달되지 않음이 표시됩니다. Guard가 차단한 쓰기에는 코멘트할 수 없습니다.

지시 입력란도 그대로 있습니다. 실행을 취소하지 않고 자유 텍스트로 에이전트의 방향을 바꿀 때 씁니다("마이그레이션은 건너뛰고 핸들러에 집중해"). 줄 코멘트는 같은 메커니즘을 한 줄에 고정한 것입니다. 덕분에 생략할 수 있는 것은 서두입니다. "docs/setup.md에서 go build라고 쓴 부분 말인데"라는 정보는 이미 메시지에 들어 있습니다.

리뷰할 것이 없던 실행

변경 사항을 만들던 중에, 저는 한 실행에 우리 Git 저장소 중 하나에 문서를 추가해 달라고 요청했고, 보기가 계속 비어 있는 것을 지켜봤습니다. 파일도, diff도, 코멘트할 대상도 없었습니다.

프로젝트에 연결된 저장소가 없었기 때문에 Archyl은 아무것도 클론하지 않았습니다. 대신 그 실행에는 GitHub 커넥터가 있었고, 에이전트는 눈앞의 도구로 합리적인 일을 했습니다. 커넥터의 push_files 도구로 파일을 GitHub에 직접 쓴 것입니다. 워크스페이스를 거친 것은 아무것도 없었습니다. 그러니 Guard를 거친 것도, 변경 사항에 나타난 것도 없었고, 제가 만들던 리뷰 루프에는 리뷰할 것이 없었습니다.

이제 에이전트는 두 경우 모두 워크스페이스에서 작업합니다.

• 프로젝트에 저장소가 연결되어 있는 경우. 이전과 같이 실행이 시작될 때 Archyl이 클론합니다.
• 연결된 저장소는 없지만 GitHub 커넥터가 연결된 경우. 에이전트가 파일을 건드리기 전에 커넥터의 자격 증명으로 open_repository를 호출해, 작업 대상 저장소를 직접 클론합니다. 이 방식은 GitHub에서 호스팅하는 MCP 서버(api.githubcopilot.com)에서만 동작하며, 토큰에는 저장소 접근 권한이 있어야 합니다.

워크스페이스가 열리면 저장소에 쓰는 커넥터 도구(push_files, create_or_update_file, delete_file, create_pull_request)는 거부되고, 에이전트는 다음 메시지를 읽습니다.

a repository workspace is open: change files with write_file and edit_file instead. Archyl commits your changes and opens the pull request when the run ends.

이 규칙이 있기 때문에 모든 변경이 Guard를 거치고, 변경 사항에 나타나며, 하나의 pull request로 모입니다.

실행이 끝나면

Archyl은 워크스페이스의 변경 사항을 실행 ID의 앞 여덟 글자를 사용한 archyl/agent-<run id>에 커밋하고, 클론이 시작된 브랜치를 대상으로 pull request를 엽니다. 링크는 변경 사항 상단(풀 리퀘스트 열기)과 결과에 있습니다. 무엇이 게시되는지는 실행이 어떻게 끝났는지에 따라 정해집니다.

GitLab에서는 드래프트가 Draft: 머지 리퀘스트입니다. Bitbucket에서는 pull request 없이 브랜치만 푸시합니다. 파일을 하나도 변경하지 않은 실행은 아무것도 게시하지 않습니다.

코멘트가 다음 실행이 됩니다

실행이 멈춰도 리뷰는 멈추지 않습니다. pull request는 열려 있고, 당신은 변경 사항에서 최종 diff를 읽고 있습니다. 끝난 실행에 남긴 코멘트는 전달할 에이전트가 없으므로 다음 실행을 위한 메모가 됩니다. 후속 실행에 추가를 누르면 브라우저에 보관됩니다. 파일 목록 위의 막대가 그 수를 세고(후속 실행용 코멘트 3개) 이 코멘트로 이어서 실행을 제안합니다.

끝난 실행에는 결과와 상관없이 두 개의 버튼이 있습니다. 다시 실행은 같은 작업과 프로필로 시작 대화 상자를 열어 처음부터 새로 실행합니다. 첫 시도가 그 위에 쌓고 싶지 않은 방향으로 흘러갔을 때 알맞은 선택입니다. 이어서 실행은 이 실행의 작업을 이어받는 새 실행을 시작하며, 후속 실행용 코멘트를 남겼다면 지시 사항에 한 줄에 하나씩 미리 채워집니다.

- docs/setup.md:28 — Say that make seed needs the database container running.
- docs/setup.md:44 — Add how to run the tests for a single package.
- README.md:18 (removed line) — Keep the troubleshooting note for port 5432, setup.md doesn't have it.

원하는 대로 수정하면 됩니다. 프로필은 기본적으로 원래 실행과 같으며, 커넥터를 선택할 수 있습니다.

같은 브랜치, 같은 pull request

이어 가는 실행은 프롬프트만 길어진 새 실행이 아닙니다. 이전 실행이 게시한 브랜치에서 시작해 그 브랜치에 커밋하고, 새 pull request를 여는 대신 같은 pull request에 변경 사항을 추가합니다. 이전 실행이 GitHub 커넥터로 저장소를 열었다면, 에이전트가 시작되기 전에 그 브랜치로 저장소를 다시 엽니다.

에이전트는 무엇을 이어받는지도 전달받습니다. 이전 작업, 그 실행이 한 일(결과 요약 또는 멈춘 이유), 그 작업이 어디에 있는지가 모두 프롬프트 맨 앞에 들어갑니다(ID, URL, 요약은 예시입니다).

# Continuing a previous run
This run continues the work of run `4f1c2a9e-7b3d-4e0a-9c6f-2d8b1a5e3c70`. Build on what it did rather than starting over.

## What it was asked
Document how to set up and run the service locally.

## What it did
Added docs/setup.md with prerequisites, environment variables and the make targets, and linked it from the README. Left the staging database out, as answered.

Its changes are on the branch `archyl/agent-4f1c2a9e`, which your workspace starts from. Your changes are added to its pull request: https://github.com/acme/billing/pull/212. If the workspace could not start from that branch, the run feed says so and your changes go to a new pull request.

The task below is what the person wants now, often review comments on that work: address each of them.

리뷰어는 pull request가 줄줄이 쌓이는 것이 아니라 하나의 pull request가 자라는 모습을 보게 됩니다. GitHub의 Copilot cloud agent도 후속 작업을 같은 방식으로 처리합니다. pull request 코멘트에서 @copilot을 멘션하면, 기본적으로 그 pull request의 브랜치에 커밋을 푸시합니다(GitHub Docs). 작업 하나에 pull request 하나가 올바른 형태이고, 이어 가는 실행도 그 형태를 지킵니다.

경계 상황에서는 다음과 같이 동작합니다.

• 브랜치가 사라진 경우, 예를 들어 병합 후 삭제된 경우입니다. 이어 가는 실행은 기본 브랜치에서 시작해 새 pull request를 열고, 피드에는 그 사실을 알리는 주황색 줄이 나타납니다. "이전 실행의 브랜치 archyl/agent-4f1c2a9e를 체크아웃하지 못했습니다. 이 실행은 기본 브랜치에서 시작하며 새 풀 리퀘스트를 엽니다."
• pull request가 드래프트인 경우. 드래프트로 남습니다. 작업이 끝나면 리뷰 준비 완료로 표시하세요.
• 에이전트 브랜치만 해당됩니다. Archyl은 자신의 에이전트가 만든 브랜치, 즉 archyl/ 아래의 브랜치에서만 이어 가며, 사람이 만든 브랜치에는 절대 커밋하지 않습니다.

두 실행은 서로 연결됩니다. 새 실행에는 원래 실행이, 이전 실행에는 후속 실행이 표시됩니다. 아직 진행 중인 실행은 이어 갈 수 없습니다. 대신 그 줄에 코멘트를 다세요.

이어 가는 실행은 아키텍처 컨텍스트도 유지합니다. 이 실행의 작업 세션은 후속 요청만이 아니라 이전 작업과 후속 요청을 합친 내용으로 열리므로, 이어 가는 원래 실행과 같은 아키텍처 요소와 메모리를 찾습니다. 이것은 생각보다 중요합니다. "make seed를 실행하려면 데이터베이스 container가 떠 있어야 한다고 적어 주세요"라는 줄은 서비스 이름을 하나도 담고 있지 않아서, 이 줄만으로 연 세션은 연결할 대상이 거의 없을 것입니다.

하지 않는 것

워커에는 셸이 없습니다. 파일을 읽고, 쓰고, 편집하고, 나열하고, 검색할 수는 있지만 프로젝트를 빌드하거나 테스트를 실행할 수는 없습니다. 이 예시에서 Makefile은 읽을 수 있어도, 문서가 맞는지 확인하려고 make build를 실행할 수는 없습니다. 깨끗한 diff가 통과한 빌드를 뜻하지는 않으며, 그 일은 여전히 CI가 합니다.

줄 코멘트는 안내일 뿐 게이트가 아닙니다. 해결됨 상태가 없고, 에이전트가 코멘트를 반영했는지 확인하는 장치도 없습니다. diff에서 에이전트의 다음 편집을 보고 판단하는 것은 당신입니다.

후속 실행용 메모는 브라우저 하나에만 남습니다. 실행을 이어 가기 전까지, 후속 실행에 추가한 코멘트는 팀원에게 보이지 않습니다. 작업 중인 에이전트에게 보낸 코멘트는 다릅니다. 피드에 남아 모두가 볼 수 있습니다.

계획 검토는 누군가 있다는 것을 전제로 합니다. 프로필 단위 설정이며 기본값은 꺼짐이고, 그 프로필의 모든 실행이 이 설정을 따릅니다. 예약된 실행도 마찬가지입니다. 검토가 켜진 프로필에서 새벽 3시에 시작된 실행은 1시간을 기다린 뒤 아무것도 변경하지 않고 실패합니다. 질문도 1시간을 기다린 뒤, 에이전트가 혼자 결정합니다.

커넥터를 통한 클론은 GitHub 전용입니다. open_repository는 GitHub에서 호스팅하는 MCP 서버에서 동작합니다. 다른 호스트라면 저장소를 프로젝트에 연결하세요.

어디서 시작할까

어차피 리뷰할 작은 작업을 하나 골라, 계획 먼저 검토를 켠 프로필에서 실행하세요. 실행 페이지는 열어 두세요. 승인하기 전에 계획을 수정하세요. 요청하지 않았을 단계를 지우는 것뿐이어도 괜찮습니다. 변경 사항에서 pull request였다면 지적했을 첫 번째 줄에 코멘트하고, 그것이 대기 중에서 전달됨으로 바뀌는 것을 지켜보세요. 실행이 끝나면 나머지는 후속 실행용 코멘트로 남기고 이어서 실행을 누르세요.

예약 실행에 쓰는 프로필에서는, 리뷰하려고 깨어 있을 사람이 없는 한 계획 검토를 꺼 두세요.

계획, 질문, 실시간 diff, 줄 코멘트, 이어 가는 실행은 Archyl 관리형 에이전트 실행의 일부입니다. 위에서 언급한 모든 설정과 레이블은 관리형 에이전트 실행 문서에 있습니다. 함께 읽을 글: 이 기능의 기반이 되는 Guard와 작업 세션에 대해서는 관리형 에이전트가 이제 Harness의 통제를 받습니다를, 그리고 관리형 에이전트 실행 출시 소식을 참고하세요.