Agentation

Agentation: AI 코딩 에이전트를 위한 스마트 UI 주석 도구

AI 기반 개발 시대에 가장 큰 병목 현상은 인간의 의도를 AI에게 정확히 전달하는 것입니다. Agentation은 UI 주석을 AI 코딩 에이전트가 즉각적으로 이해하고 실행할 수 있는 **구조화된 컨텍스트(Structured Context)**로 변환하여 이 문제를 해결합니다.

단순히 "파란색 버튼을 수정해 줘"라고 모호하게 설명하는 대신, Agentation을 사용하면 정확한 CSS 선택자, 소스 파일 경로, React 컴포넌트 계층 구조를 AI에게 제공할 수 있습니다. 본 가이드에서는 Agentation v3.0.2의 주요 기능과 활용법을 자세히 살펴봅니다.

---

What's Agentation?

Agentation은 웹 애플리케이션의 UI 요소에 주석을 달고, 이를 AI 코딩 에이전트(Claude Code, Codex, Cursor 등)가 이해할 수 있는 데이터 형식으로 변환해 주는 도구입니다.

사용자가 브라우저에서 특정 요소를 클릭하고 메모를 추가하면, Agentation은 해당 요소의 메타데이터를 추출합니다. 이 데이터에는 다음이 포함됩니다:

• CSS 선택자: 코드베이스에서 요소를 직접 찾기 위한 경로
• 소스 파일 경로: 수정해야 할 파일의 정확한 위치
• React 컴포넌트 트리: UI의 구조적 계층 이해
• 계산된 스타일(Computed Styles): 현재 요소의 외형 정보

이 모든 정보는 마크다운 형식으로 출력되어 AI 도구에 즉시 붙여넣거나, **MCP(Model Context Protocol)**를 통해 자동으로 동기화될 수 있습니다.

Features (주요 기능)

Agentation은 개발자와 AI 에이전트 간의 원활한 소통을 위해 설계된 강력한 기능들을 제공합니다.

1. 시각적 피드백 및 주석 처리

• 요소 하이라이트: 마우스를 올리면 요소의 이름이 강조되어 정확한 선택이 가능합니다.
• 애니메이션 일시 중지: 복잡한 애니메이션 중간의 특정 프레임을 멈추고 주석을 달 수 있습니다.
• 텍스트 선택 주석: 오타 수정이나 콘텐츠 이슈의 경우 특정 텍스트를 선택하여 피드백을 남길 수 있습니다.

2. 고도화된 데이터 출력

• 표준 및 React 컴포넌트 정보: 일반 HTML 요소뿐만 아니라 React 컴포넌트 정보를 포함합니다.
• 마커 색상 설정: 가독성을 위해 주석 마커의 색상을 변경할 수 있습니다.
• AFS 1.1 (Annotation Format Schema): 표준화된 스키마를 사용하여 AI와의 호환성을 높였습니다.

3. 강력한 통합 기능

• MCP Connection: MCP를 사용하면 복사-붙여넣기 없이 AI 에이전트가 사용자가 가리키는 요소를 실시간으로 볼 수 있습니다.
• Webhooks & API: 라이브 주석 데이터를 외부 서비스로 전송하거나 자체 통합 도구를 빌드할 수 있습니다.
• Auto-Send: 주석 변경 사항을 실시간으로 웹훅 URL에 전송합니다.

How to Use (사용 방법)

Agentation을 설치하고 활용하는 방법은 매우 간단합니다.

설치 방법

터미널에서 다음 명령어를 실행하여 설치합니다:

npm install agentation

단계별 활용 가이드

1. 활성화: 화면 우측 하단의 아이콘을 클릭하여 기능을 활성화합니다.
2. 요소 선택: 수정이 필요한 UI 요소 위로 마우스를 가져가 이름을 확인합니다.
3. 주석 추가: 요소를 클릭하고 피드백 내용을 입력한 뒤 'Add'를 클릭합니다.
4. 복사 및 전달: 아이콘을 클릭하여 포맷된 마크다운을 복사한 후, Claude Code나 사용 중인 AI 에이전트에 붙여넣습니다.

   참고: MCP를 사용 중이라면 복사 과정 없이 "내 피드백을 처리해 줘" 또는 "3번 주석을 수정해"라고 말하기만 하면 됩니다.

Use Case (활용 사례)

AI 에이전트와의 협업

AI 도구가 코드베이스에 접근 권한이 있는 경우(Cursor, Claude Code 등), Agentation의 출력값은 강력한 내비게이터 역할을 합니다.

• 정확한 탐색: .sidebar > button.primary와 같은 상세 경로를 통해 AI가 grep 명령어로 파일 위치를 즉시 찾습니다.
• 디자인 수정: 패딩, 색상 등 계산된 스타일 정보를 기반으로 AI에게 정확한 디자인 가이드를 제시합니다.
• 양방향 소통: MCP 통합 시 AI가 "주석에 대해 질문이 있습니다"라며 응답하거나 수정을 완료한 후 주석을 해결(Resolve)할 수 있습니다.

협업 베스트 프래티스

• 구체성 유지: "이거 고쳐줘" 대신 "버튼 텍스트가 불분명함"과 같이 구체적으로 작성하세요.
• 이슈 분리: 하나의 주석에는 하나의 이슈만 담아 AI가 개별적으로 처리하기 쉽게 만드세요.
• 컨텍스트 포함: 기대했던 결과와 실제 결과의 차이를 명시하세요.

FAQ (자주 묻는 질문)

Q: Agentation은 유료인가요? A: 개인 및 기업의 내부 용도로는 무료로 사용할 수 있습니다. 다만, Agentation을 상업적 제품의 일부로 재배포하려는 경우에는 별도의 커머셜 라이선스 문의가 필요합니다.

Q: 어떤 AI 도구와 호환되나요? A: Claude Code, Cursor, Codex 등 마크다운 입력을 받거나 코드베이스 접근 권한이 있는 모든 AI 에이전트와 호환됩니다. 특히 MCP 지원 도구에서 최고의 성능을 발휘합니다.

Q: MCP 연결의 장점은 무엇인가요? A: MCP를 통해 에이전트가 실시간으로 주석을 확인하므로 수동으로 데이터를 전달할 필요가 없으며, 에이전트가 주석 목록을 조회하거나 질문을 던지는 등 대화형 피드백이 가능해집니다.

---

Made by Benji Taylor, Dennis Jin, and Alex Vanderzon