Skip to content
Merged
Show file tree
Hide file tree
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,10 @@ SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
# Umami Analytics (self-hosted)
NEXT_PUBLIC_UMAMI_URL=https://your-umami.vercel.app
NEXT_PUBLIC_UMAMI_WEBSITE_ID=your-website-id

# Agentation (dev overlay)
NEXT_PUBLIC_AGENTATION_ENDPOINT=http://localhost:4747
NEXT_PUBLIC_AGENTATION_WEBHOOK_URL=/api/agentation/webhook
AGENTATION_AUTORUN_ENABLED=true
# Optional: override default codex command executed on webhook
# AGENTATION_AUTORUN_COMMAND="codex exec --full-auto -C /absolute/path 'watch mode로 계속 처리해줘'"
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -40,3 +40,4 @@ next-env.d.ts
.husky/
.sisyphus/
.claude/
/.agentation/
92 changes: 92 additions & 0 deletions docs/guides/agentation-workflow.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# Agentation 좌표 기반 작업 가이드

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

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

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

```bash
npm run dev
```

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

```bash
NEXT_PUBLIC_AGENTATION_ENDPOINT=http://localhost:4747
```

## 2. Codex MCP 서버 등록

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

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

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

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

## 3. Agentation MCP 서버 실행

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

```bash
npx agentation-mcp server
```

기본 포트는 `4747`이에요.

## 4. 실제 작업 흐름

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

## 4-1. Webhook 자동 실행 흐름

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

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

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

```bash
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`로 호출해요.

```bash
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 메시지에 변경 파일 경로를 남겨요.
14 changes: 14 additions & 0 deletions next.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,20 @@ const nextConfig = {
images: {
formats: ['image/avif', 'image/webp'],
},
async redirects() {
return [
{
source: '/blog',
destination: '/engineering',
permanent: true,
},
{
source: '/series',
destination: '/engineering?type=series',
permanent: true,
},
];
},
async headers() {
return [
{
Expand Down
Loading
Loading