Agentation 좌표 기반 작업 가이드

이 가이드는 Agentation 오버레이와 Agentation MCP를 함께 써서 화면 좌표 기반으로 UI 변경점을 빠르게 전달하는 흐름을 정리해요.

1. 프로젝트에서 오버레이 켜기

개발 서버를 실행하면 화면 오른쪽 아래에 Agentation 툴바가 보여요.

npm run dev

기본 엔드포인트는 http://localhost:4747이고, 필요하면 환경변수로 바꿔서 쓸 수 있어요.

NEXT_PUBLIC_AGENTATION_ENDPOINT=http://localhost:4747

2. Codex MCP 서버 등록

아래 명령으로 Codex에 Agentation MCP를 등록해요.

npx -y add-mcp@latest agentation-mcp -a codex -g -y

등록 후 ~/.codex/config.toml에 mcp_servers.agentation 항목이 생겼는지 확인해요.

[mcp_servers.agentation]
command = "npx"
args = ["-y", "agentation-mcp", "server"]

3. Agentation MCP 서버 실행

아래 명령으로 HTTP + MCP 서버를 같이 실행해요.

npx agentation-mcp server

기본 포트는 4747이에요.

4. 실제 작업 흐름

웹 화면에서 Agentation 툴바를 켜요.
수정하고 싶은 UI 요소를 클릭하거나 영역을 드래그해요.
코멘트를 남기고 전송해요.
Codex에서 Agentation MCP 도구로 새 annotation을 받아요.
코드 수정 후 annotation을 resolve 처리해요.

4-1. Webhook 자동 실행 흐름

개발 환경에서는 코멘트를 등록하면 webhook으로 자동 실행을 바로 트리거해요.

기본 webhook URL: /api/agentation/webhook
기본 동작: annotation.add 또는 submit 이벤트가 들어오면 codex exec를 자동 실행해요.
중복 실행 방지: .agentation/autorun.lock.json 락 파일로 한 번에 한 프로세스만 실행해요.
로그 경로: .agentation/autorun.log

환경변수로 동작을 조정할 수 있어요.

NEXT_PUBLIC_AGENTATION_WEBHOOK_URL=/api/agentation/webhook
AGENTATION_AUTORUN_ENABLED=true
AGENTATION_AUTORUN_COMMAND="codex exec --full-auto -C /Users/noah/workspace/personal/eunu.log 'watch mode로 계속 처리해줘'"

AGENTATION_AUTORUN_COMMAND를 지정하지 않으면 기본 codex exec --full-auto 명령을 사용해요.

실행 전 연결만 확인하고 싶으면 dryRun=1로 호출해요.

curl -X POST 'http://localhost:3000/api/agentation/webhook?dryRun=1' \
  -H 'Content-Type: application/json' \
  -d '{"event":"annotation.add","annotation":{"id":"demo"}}'

5. 자주 쓰는 점검

오버레이가 안 보이면 개발 환경인지 확인해요.
annotation이 전송되지 않으면 agentation-mcp server 실행 상태를 확인해요.
MCP가 안 잡히면 Codex를 재시작해요.

6. 권장 운영 방식

한 annotation에는 한 작업만 담아요.
"무엇을 어떻게"를 짧게 적어요.
수정 완료 후 resolve 메시지에 변경 파일 경로를 남겨요.

FilesExpand file tree

agentation-workflow.md

Latest commit

History