프론트엔드 개발자로 일하면서 AI 현명하게 사용하기 (feat. Agentation)

1. Agentation이란?

Agentation은 한마디로 **“AI 에이전트를 위한 비주얼 피드백 도구”**다.

프론트엔드 개발을 하다 보면 이런 경험을 자주 한다.

AI에게 “이 버튼 좀 왼쪽으로 옮겨줘”라고 말하고 싶은데, 어떤 버튼인지 설명하기가 귀찮다.
디자인 수정 사항을 텍스트로 일일이 설명하는 게 엄청 비효율적이다.
AI가 수정한 결과물을 보고 “여기 아니고 저기!”라고 다시 알려줘야 한다.

Agentation은 이 문제를 깔끔하게 해결해 준다. 브라우저 화면에서 직접 UI 요소를 클릭하고 메모를 남기면, 그 정보가 구조화된 컨텍스트로 AI 에이전트에게 전달된다. 복사-붙여넣기를 할 수도 있고, MCP(Model Context Protocol)로 실시간 연동할 수도 있다.

핵심 기능 요약

기능	설명
요소 클릭 Annotation	브라우저에서 아무 요소나 클릭하고 수정 사항을 메모
텍스트 선택 Annotation	텍스트를 드래그해서 오타나 내용 수정 요청
영역 선택 / 멀티 셀렉트	여러 요소를 한번에 선택하여 맥락 전달
React 컴포넌트 감지	클릭한 요소의 React 컴포넌트 계층 구조 자동 탐지
Computed Style 확인	선택한 요소의 CSS 속성값을 팝업으로 바로 확인
MCP 서버 연동	Claude Code 등 AI 에이전트와 실시간 양방향 통신
레이아웃 모드	컴포넌트 배치, 섹션 재배열을 시각적으로 요청

특히 React 컴포넌트 감지 기능이 꽤 유용하다. 화면에서 어떤 요소를 클릭하면, 단순히 HTML 태그 정보만 전달하는 게 아니라 App > Dashboard > MetricCard > ... 같은 컴포넌트 트리까지 보여준다. AI 에이전트가 코드베이스에서 해당 컴포넌트를 grep으로 즉시 찾을 수 있도록 돕는 구조다.

2. 설치 및 사용 방법

최근 진행 중인 프론트엔드 프로젝트에 Agentation을 직접 셋팅해봤다. 기술 스택은 다음과 같다.

항목	선택
Framework	React 19
Build	Vite 8
Styling	TailwindCSS v4
Routing	React Router v7
Server State	TanStack Query v5

Step 1. 패키지 설치

npm install agentation -D

devDependencies로 설치한다. 프로덕션 번들에는 포함되지 않는다.

Step 2. 앱에 컴포넌트 추가

앱 루트 레벨에 <Agentation /> 컴포넌트를 추가한다. NODE_ENV 체크를 넣어 개발 환경에서만 로드되도록 설정했다.

import { Agentation } from "agentation";

function App() {
  return (
    <>
      <YourApp />
      {process.env.NODE_ENV === "development" && <Agentation />}
    </>
  );
}

이것만으로 브라우저 우측 하단에 Agentation 툴바가 생긴다. 여기서 바로 요소를 클릭하고 annotation을 달 수 있다. Copy 버튼을 누르면 구조화된 마크다운이 클립보드에 복사되고, 이걸 Claude Code나 다른 AI 도구에 붙여넣기하면 된다.

Step 3. MCP 서버 연동 (권장)

한 단계 더 나아가 MCP 서버를 연동하면 복사-붙여넣기 없이 AI 에이전트가 실시간으로 annotation을 읽고 처리할 수 있다.

# MCP 서버 패키지 설치
npm install agentation-mcp

# Claude Code에 MCP 서버 등록
npx add-mcp "npx -y agentation-mcp server"

# 또는 Claude Code 전용 위저드
npx agentation-mcp init

# 셋업 확인
npx agentation-mcp doctor

MCP 서버는 기본적으로 4747 포트에서 실행된다. 컴포넌트에 endpoint를 지정해주면 연동 완료다.

<Agentation
  endpoint="http://localhost:4747"
  onSessionCreated={(sessionId) => {
    console.log("Session started:", sessionId);
  }}
/>

MCP 연동 시 제공되는 도구들

MCP를 통해 AI 에이전트에게 제공되는 9개의 도구 목록이다.

Tool	설명
`agentation_list_sessions`	모든 활성 annotation 세션 목록 조회
`agentation_get_session`	특정 세션의 모든 annotation 조회
`agentation_get_pending`	미처리 annotation 조회
`agentation_get_all_pending`	전체 세션에서 미처리 annotation 조회
`agentation_acknowledge`	annotation 확인 처리
`agentation_resolve`	annotation 해결 완료 처리
`agentation_dismiss`	annotation 반려 (사유 포함)
`agentation_reply`	annotation 스레드에 답글 추가
`agentation_watch_annotations`	새 annotation 등장까지 대기 후 배치 반환

이 도구들 덕분에 AI 에이전트가 브라우저에서 남긴 피드백을 직접 읽고, 처리하고, 완료 표시까지 가능하다.

동작 흐름 요약

브라우저(Toolbar) → HTTP Server → MCP Server → AI Agent(Claude)
     ↑                                              ↓
     └──────────── resolved / dismissed ────────────┘

브라우저에서 요소를 클릭하고 “이 버튼 색상 변경해줘” annotation 작성.
Agentation이 해당 요소의 셀렉터, React 컴포넌트 경로, computed style 등을 구조화한다.
MCP 서버를 통해 Claude Code가 해당 annotation을 읽는다.
Claude가 코드를 수정한 뒤 agentation_resolve로 완료 처리한다.
브라우저에서 해당 마커가 resolved 상태로 변경된다.

3. 커스텀 스킬: `/apply-agentation-annotations`

Agentation + MCP 조합에 익숙해지면서, 한 단계 더 자동화를 올리고 싶어졌다. 그래서 Claude Code에 /apply-agentation-annotations라는 커스텀 스킬을 직접 만들었다.

이 스킬이 하는 일

Agentation MCP로 프로젝트를 연동한 상태에서, 브라우저에서 작성해둔 annotation을 AI가 직접 읽는다.
annotation 내용을 분석하여 해당 이슈를 코드 수정으로 처리한다.
수정이 완료되면 해당 annotation을 자동으로 resolve 처리한다.

왜 만들었나?

MCP 연동만으로도 편리하지만, 매번 “annotation 읽어줘 → 처리해줘 → 완료 표시해줘”를 단계별로 지시하는 건 귀찮다. 이 스킬을 만들어 두면 단 한 줄이면 된다.

/apply-agentation-annotations

이 명령어를 실행하면 Claude가 알아서 현재 pending annotation을 전부 가져와 요청 사항을 해석하고, 코드를 수정한 뒤 완료된 annotation을 resolve 처리한다.

실제 워크플로우 예시

브라우저에서 개발 서버 실행 (npm run dev).
Agentation 툴바로 수정이 필요한 부분에 annotation 작성.
- “이 카드 padding 좌우 16px → 20px로 변경”
- “이 텍스트 색상 #666에서 var(—c-text-sub)로 변경”
- “이 버튼 hover 시 배경색 추가”
Claude Code에서 /apply-agentation-annotations 실행.
Claude가 자동으로 전부 처리하고 annotation을 정리한다.
브라우저를 새로고침하여 확인하면 끝.

결국 코드를 장황하게 설명하는 대신 화면을 가리키기만 하면 된다. “두 번째 섹션의 세 번째 카드 컴포넌트의…”라고 구구절절 적을 필요가 없어진다.

4. 쓰는 이유와 느낀 점

✅ 왜 쓰는가

1. “맥락 전달”의 비용이 극적으로 줄어든다.

프론트엔드 개발에서 AI에게 가장 어려운 건 “어디를 수정해야 하는지” 알려주는 것이다. 컴포넌트 이름, 파일 경로, 셀렉터를 텍스트로 설명하는 오버헤드가 완전히 사라진다. 그냥 클릭 한 번이면 된다.

2. AI가 “시각적 컨텍스트”를 이해한다.

Agentation은 단순히 DOM 셀렉터만 전달하는 게 아니라, React 컴포넌트 계층, computed CSS 속성, 요소의 텍스트 콘텐츠까지 구조화해서 전달한다. 덕분에 AI가 코드베이스에서 해당 위치를 찾는 정확도가 확연히 올라간다.

3. 반복 피드백 사이클이 자동화된다.

커스텀 스킬과 결합하면, “피드백 작성 → 코드 수정 → 확인” 사이클이 거의 원클릭으로 줄어든다. 자잘한 수정 사항들을 한 번에 모아서 털어내기 좋다.

4. 비개발자와의 협업에도 유용하다.

디자이너나 PM이 브라우저에서 직접 annotation을 달 수 있다. “여기 간격 좀 넓혀주세요”를 스크린샷 캡처하고 빨간 펜으로 그리는 대신, 정확한 요소에 메모로 남길 수 있다.

💬 실사용 느낀 점

셋팅이 아주 간단하다. npm install 하고 컴포넌트 하나만 얹으면 끝이다. MCP 연동 위저드도 잘 되어 있다.
React 컴포넌트 감지가 생각보다 정확하다. 내 프로젝트에서 Table > TBody > TRow 같은 계층 구조를 찰떡같이 잡아내는 걸 보고 감탄했다.
Local-first 설계가 편리하다. 서버가 꺼져 있어도 annotation이 로컬에 잘 보존되고, 서버가 켜지면 싱크된다. 페이지를 새로고침해도 세션이 계속 유지된다.
의존성 걱정 없다. React 외에 런타임 의존성이 없어서 프로젝트가 무거워질 염려가 없다. 개발 환경에서만 켜지도록 분기처리해두면 안심이다.
다만 데스크톱 전용이다. 모바일 반응형 화면을 테스트할 때는 쓸 수 없다는 점이 아쉽다. 아직 얼리 스테이지 도구라 간혹 삐끗할 때가 있다.

🧠 프론트엔드 개발자가 AI를 현명하게 쓰는 법

결국 AI 도구를 잘 쓰는 핵심은 **“좋은 맥락을 전달하는 것”**이라고 생각한다. 아무리 똑똑한 AI라도 내가 뭘 원하는지 모르면 삽질할 뿐이다.

Agentation은 이 “맥락 전달” 과정을 아주 우아하게 단축해 준다. 내가 직접 코드를 뒤져가며 설명하는 대신, 화면에서 콕 찝어 가리키면 된다. 여기에 MCP 연동과 커스텀 스킬까지 끼얹으면, AI가 알아서 피드백을 수거해 UI를 고쳐놓는 자율 워크플로우를 만들 수 있다.

프론트엔드 개발자에게 AI는 단순한 “코드 생성기”가 아니라, **“내 피드백을 알아듣고 행동하는 동료”**로 활용할 때 진짜 진가를 발휘하는 것 같다.