AI 에이전트로 PodoLay 플러그인 만들기

Claude Code, Codex, Antigravity, Cursor, VS Code(GitHub Copilot) 같은 AI 코딩 에이전트에게 PodoLay 플러그인을 만들게 하는 방법을, 프로그램 설치부터 첫 플러그인 폴더를 만들고 첫 요청을 하기까지 차례대로 설명한다. 터미널을 거의 써 본 적이 없어도 따라 할 수 있게 썼다. 에이전트 프로그램은 자주 바뀐다 — 설치 방법·요금은 2026년 10월 기준이며, 다르면 각 에이전트의 공식 안내를 따른다.

목차

1. 어떻게 돌아가나
2. 에이전트 고르기
3. 공통 준비 — 터미널·Node.js·Chrome
4. SDK 내려받기
5. 첫 플러그인 폴더 만들기 — init
6. Claude Code
7. Codex (OpenAI)
8. Antigravity CLI (Google)
9. Cursor
10. VS Code + GitHub Copilot
11. 첫 요청 — 무엇을 어떻게 말할까
12. 사람이 할 일
13. 문제가 생기면

1. 어떻게 돌아가나

PodoLay 플러그인 SDK 는 AI 에이전트가 혼자서 만들고 시험하고 고칠 수 있게 만들어져 있다.

• node tools.mjs init 이 플러그인 폴더를 만들 때 에이전트용 지침 파일 AGENTS.md 를 함께 만든다. 플러그인 API 의 규칙, 써야 할 명령, 끝났다고 말하기 전에 확인할 것이 들어 있다. 대부분의 에이전트(Codex, Antigravity, Cursor, Copilot)는 폴더를 열면 이 파일을 저절로 읽는다. Claude Code 는 CLAUDE.md 를 읽는데, SDK 가 만든 CLAUDE.md 는 @AGENTS.md 한 줄이라 결국 같은 지침을 읽는다.
• 에이전트는 코드를 쓴 뒤 check(편집기 없이 검사)와 node test.mjs(모의 편집기 시험)로 스스로 확인하고, 샌드박스 편집기(로그인 없이, 서버에 아무것도 저장하지 않는 진짜 편집기)에서 같은 시험을 돌리고 쪽 그림(PNG)을 찍어 눈으로도 확인한다.
• 사람은 무엇을 만들지 말하고, 에이전트가 묻는 명령 실행을 허락하고, 브라우저에서 결과를 보고, 다 되면 포털에 올린다.

작업 폴더 (예: 문서/podolay)
├── podolay-plugin-sdk-1.6.2/   ← 내려받아 푼 SDK (tools.mjs, 안내서, 예제) — 폴더 이름에 SDK 판
└── my-plugin/            ← init 이 만든 내 플러그인 — 에이전트는 여기서 연다
    ├── podolay-plugin.json   매니페스트
    ├── main.js               플러그인 코드
    ├── AGENTS.md · CLAUDE.md 에이전트 지침
    ├── test.mjs              시험
    └── podolay-plugin.d.ts · jsconfig.json  타입 정의(자동완성)

2. 에이전트 고르기

어느 것이든 된다. 이미 쓰는 것이 있으면 그것을 쓴다.

• 터미널형(Claude Code·Codex·Antigravity)은 명령을 직접 돌리고 결과를 읽으며 오래 혼자 일하는 데 강하다. SDK 의 시험·샌드박스 조종이 모두 터미널 명령이라 잘 맞는다.
• 편집기형(Cursor·VS Code)은 코드가 화면에 보여 따라가기 쉽다. 이들도 안에서 터미널 명령을 돌린다(실행 전에 묻는다).

3. 공통 준비 — 터미널·Node.js·Chrome

3.1 터미널 열기

• macOS: Spotlight(⌘ Space)에서 "터미널" 또는 "Terminal" 을 찾아 연다.
• Windows: 시작 메뉴에서 "PowerShell" 또는 "터미널(Windows Terminal)" 을 연다. 프롬프트가 PS C:\Users\이름> 처럼 PS 로 시작하면 PowerShell 이다.

이 안내의 명령은 한 줄씩 복사해 터미널에 붙이고 Enter 를 누르면 된다. # 뒤는 설명이라 치지 않아도 된다.

3.2 Node.js 설치 (18 이상, LTS 권장)

SDK 의 도구는 Node.js 로 돈다. 다른 것은 깔 필요가 없다(SDK 는 다른 패키지에 기대지 않는다).

• macOS: https://nodejs.org 에서 LTS 설치 파일(.pkg)을 받아 연다. Homebrew 를 쓴다면 brew install node.
• Windows: https://nodejs.org 에서 LTS 설치 파일(.msi)을 받아 연다(기본값 그대로 다음). 또는 PowerShell 에서

  winget install OpenJS.NodeJS.LTS

설치한 뒤 터미널을 새로 열고 판을 확인한다.

node -v      # v22.x.x 처럼 나오면 된다 (v18 이상)

node 를 찾을 수 없다고 나오면 터미널을 닫고 다시 연다. 그래도 안 되면 컴퓨터를 다시 시작한다.

3.3 Google Chrome

샌드박스 편집기를 브라우저로 여는 데 쓴다. 이미 있으면 넘어간다 — https://www.google.com/chrome/. (에이전트가 화면 없이 편집기를 띄우는 --headless 는 Chrome 과 Playwright 패키지가 있어야 한다 — 필요하면 에이전트가 안내한다.)

4. SDK 내려받기

1. 작업 폴더를 하나 만든다. 예: 문서 폴더 안에 podolay.
2. 개발자 문서 맨 위의 SDK 내려받기 로 podolay-plugin-sdk-<판>.zip(예: podolay-plugin-sdk-1.6.2.zip)을 받는다.
3. 받은 zip 을 작업 폴더로 옮겨 푼다 — macOS 는 더블클릭, Windows 는 오른쪽 클릭 › 압축 풀기. podolay-plugin-sdk-<판> 폴더가 생긴다(예: podolay-plugin-sdk-1.6.2). 아래 명령의 <판> 은 이 판으로 바꿔 쓴다.

터미널로 해도 된다 — 판 없는 주소 podolay-plugin-sdk.zip 은 언제나 최신 판이다:

# macOS
mkdir -p ~/Documents/podolay && cd ~/Documents/podolay
curl -LO https://podolay.com/downloads/podolay-plugin-sdk.zip
unzip podolay-plugin-sdk.zip

# Windows (PowerShell)
mkdir $HOME\Documents\podolay; cd $HOME\Documents\podolay
Invoke-WebRequest https://podolay.com/downloads/podolay-plugin-sdk.zip -OutFile podolay-plugin-sdk.zip
Expand-Archive podolay-plugin-sdk.zip -DestinationPath .

잘 받았는지 확인한다(작업 폴더에서):

node podolay-plugin-sdk-<판>/tools.mjs --version
# PodoLay 플러그인 SDK 1.6.0 (API 1.6)

5. 첫 플러그인 폴더 만들기 — init

에이전트를 열기 전에 SDK 의 init 으로 플러그인 폴더를 만든다. 이 한 번의 명령이 플러그인 뼈대와 에이전트 지침(AGENTS.md·CLAUDE.md)·시험·타입 정의를 함께 만든다.

# 작업 폴더(podolay)에서
node podolay-plugin-sdk-<판>/tools.mjs init my-plugin --kind command --id com.myname.myplugin --name "My Plugin"

끝나면 만들었습니다: my-plugin … 과 다음 할 일이 나온다.

에이전트의 /init 은 하지 않는다. Claude Code 와 Codex 에도 /init 명령이 있는데, 이것은 에이전트가 프로젝트를 훑어 CLAUDE.md·AGENTS.md 를 새로 쓰는 명령이다. SDK 의 init 이 이미 PodoLay 에 맞춘 지침을 만들었으니 필요 없고, 실행하면 그 지침을 고치거나 덮어쓸 수 있다. 실수로 실행했다면 node ../podolay-plugin-sdk-<판>/tools.mjs upgrade . 로 SDK 지침 구역을 되살린다(덮어써졌으면 AGENTS.md 를 지우고 실행).

이제 에이전트를 my-plugin 폴더에서 연다. 아래에서 자기가 쓰는 에이전트의 절만 보면 된다.

6. Claude Code

Anthropic 의 터미널 코딩 에이전트. Claude Pro·Max·Team·Enterprise 구독이나 API(Console) 계정이 있어야 한다(무료 claude.ai 플랜은 안 된다). 터미널이 낯설면 데스크톱 앱(claude.com/download)에서도 같은 Claude Code 를 쓸 수 있다.

설치

# macOS · Linux
curl -fsSL https://claude.ai/install.sh | bash
# 또는 Homebrew
brew install --cask claude-code

# Windows (PowerShell) — 관리자 권한은 필요 없다
irm https://claude.ai/install.ps1 | iex
# 또는
winget install Anthropic.ClaudeCode

Windows 에서는 Git for Windows 를 깔아 두면 Claude Code 가 명령을 더 잘 돌린다(없으면 PowerShell 로 돌린다). 설치가 끝나면 터미널을 새로 열고 claude --version 으로 확인한다.

시작과 로그인

cd ~/Documents/podolay/my-plugin      # Windows: cd $HOME\Documents\podolay\my-plugin
claude

처음에는 브라우저가 열려 로그인한다. 폴더를 믿을지 물으면 허락한다.

지침을 읽었는지 확인 — 대화창에 /memory 를 치면 읽어 들인 지침 파일이 보인다(CLAUDE.md 와 그 안의 @AGENTS.md). 또는 "AGENTS.md 의 규칙을 세 줄로 요약해 줘" 라고 물어본다.

명령 실행 허락 — Claude Code 는 파일을 고치거나 명령(node …)을 돌리기 전에 묻는다. 내용을 보고 허락한다. 같은 종류를 매번 묻지 않게 하려면 "Yes, and don't ask again" 을 고른다. SDK 폴더(../podolay-plugin-sdk-<판>)의 안내서를 읽을 때도 처음에 묻는다.

팁

• 샌드박스 편집기를 띄우는 dev 는 계속 도는 명령이다. Claude Code 는 이것을 뒤에서 돌린다(AGENTS.md 에 그렇게 적혀 있다). 직접 띄우고 싶으면 다른 터미널에서 node ../podolay-plugin-sdk-<판>/tools.mjs dev . --open 을 돌려 두고 에이전트에게 "개발 서버는 내가 띄웠다" 고 말한다.
• 대화가 길어지면 /clear 로 새로 시작해도 된다 — 지침은 다시 읽는다.

7. Codex (OpenAI)

OpenAI 의 터미널 코딩 에이전트. ChatGPT Plus·Pro·Business·Edu·Enterprise 계정으로 로그인하거나 API 키를 쓴다.

설치

# macOS · Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# 또는 Homebrew
brew install --cask codex
# 또는 npm (Node.js 가 있으니 이것도 된다)
npm install -g @openai/codex

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

시작과 로그인

cd ~/Documents/podolay/my-plugin
codex

처음에 Sign in with ChatGPT 를 고르면 브라우저로 로그인한다.

지침 — Codex 는 폴더의 AGENTS.md 를 저절로 읽는다. "AGENTS.md 를 읽었으면 지킬 규칙을 요약해 줘" 로 확인한다. Codex 의 /init 은 하지 않는다 — AGENTS.md 를 새로 만드는 명령이다(5절).

명령 실행 허락 — /permissions 에서 Codex 가 묻지 않고 할 수 있는 일(파일 고치기·명령 실행)을 고른다. 처음에는 묻는 쪽을 권한다. 시험 명령(check·test·run)은 내 컴퓨터의 개발 서버(localhost:5199)에 붙는다 — 격리 설정 때문에 붙지 못한다고 나오면 그 명령을 허락하거나, 개발 서버를 직접 띄워 두고(6절의 팁) 다시 시키면 된다.

8. Antigravity CLI (Google)

Google 의 터미널 코딩 에이전트(agy). 예전 Gemini CLI 를 잇는다 — Google 은 2026년 6월 18일에 무료·Google One 사용자의 Gemini CLI 를 Antigravity CLI 로 바꿨다. Google 계정으로 로그인한다.

설치

# macOS · Linux
curl -fsSL https://antigravity.google/cli/install.sh | bash
# 또는 (macOS) Homebrew
brew install --cask antigravity-cli

Windows 는 Antigravity 공식 안내(https://antigravity.google)의 설치 방법을 따른다. 설치 파일은 ~/.local/bin 에 들어간다 — 터미널을 새로 열고 agy --version 이 안 되면 그 폴더를 PATH 에 더하라는 안내를 따른다.

시작과 로그인

cd ~/Documents/podolay/my-plugin
agy

브라우저가 열려 Google 계정으로 로그인한다.

지침 — Antigravity 는 폴더의 AGENTS.md(와 GEMINI.md)를 읽는다. 대화에서 "AGENTS.md 를 읽었으면 규칙을 요약해 줘" 로 확인하고, 안 읽었다고 하면 "AGENTS.md 를 먼저 읽고 그대로 따라 줘" 라고 첫 요청에 넣는다.

명령 실행 허락 — 명령을 돌리기 전에 묻는다. 설정에서 자동 허락을 켤 수도 있지만 처음에는 묻는 쪽을 권한다.

예전 Gemini CLI 를 계속 쓴다면: Gemini CLI 는 기본으로 GEMINI.md 만 읽는다. 플러그인 폴더에 .gemini/settings.json 을 만들고 { "context": { "fileName": ["AGENTS.md"] } } 를 넣거나(판에 따라 "contextFileName": "AGENTS.md"), 첫 요청에서 AGENTS.md 를 읽으라고 말한다.

9. Cursor

AI 에이전트가 들어 있는 코드 편집기 앱(VS Code 를 바탕으로 만들었다).

설치 — https://cursor.com 에서 내려받아 설치하고 Cursor 계정으로 로그인한다.

폴더 열기 — File › Open Folder… 로 my-plugin 폴더를 연다(작업 폴더나 SDK 폴더가 아니라 플러그인 폴더). AGENTS.md 가 폴더 맨 위에 있어야 Cursor 가 저절로 적용한다.

에이전트 쓰기 — 오른쪽 AI 채팅 창을 열고 모드를 Agent 로 둔다. 요청을 쓰면 파일을 고치고, 터미널 명령은 실행 전에 Run 을 누르게 한다.

지침이 안 읽힐 때 — 가끔 AGENTS.md 가 빠지는 일이 있다. 첫 요청 맨 앞에 @AGENTS.md 를 붙이면 확실히 들어간다.

팁 — jsconfig.json 과 podolay-plugin.d.ts 덕분에 main.js 에서 podolay. 를 치면 API 자동완성과 설명이 뜬다.

10. VS Code + GitHub Copilot

설치

1. https://code.visualstudio.com 에서 VS Code 를 설치한다.
2. 왼쪽 확장(Extensions)에서 GitHub Copilot 을 찾아 설치하고 GitHub 계정으로 로그인한다(Copilot 요금제 필요 — 무료 플랜은 사용량이 적다).

폴더 열기 — File › Open Folder… 로 my-plugin 폴더를 연다.

에이전트 쓰기 — Copilot 채팅 창을 열고 모드를 Agent 로 고른다. 요청을 쓰면 파일을 고치고, 터미널 명령은 실행 전에 묻는다.

지침 — VS Code 는 작업 폴더 맨 위의 AGENTS.md 를 채팅 요청에 저절로 붙인다(설정 chat.useAgentsMdFile, 기본 켜짐). 안 읽히는 것 같으면 설정에서 이 값이 켜져 있는지 보고, 첫 요청에 "AGENTS.md 를 먼저 읽어 줘" 를 넣는다.

11. 첫 요청 — 무엇을 어떻게 말할까

에이전트에게는 무엇을 만들지(누가 무엇을 하려고 쓰는지), 어떻게 부를지(메뉴·단축키·우클릭·툴), 다 됐다는 기준을 말한다. 예:

AGENTS.md 를 먼저 읽고 그대로 따라 줘.
고른 개체들에 1, 2, 3… 번호를 매기는 명령을 만들어 줘.
- 개체 우클릭 메뉴에 '번호 매기기' 로 나오고, 단축키는 ⌥⇧N.
- 번호는 각 개체의 왼쪽 위에 작은 원(빨강) 안의 흰 글자로, 한 번에 Undo 한 단계.
- 잠긴 개체는 건너뛴다.
test.mjs 에 시험을 쓰고 check·test 를 통과시킨 다음, 샌드박스 편집기에서 shot 으로 쪽 그림을 찍어 보여 줘.

AGENTS.md 를 먼저 읽고 그대로 따라 줘.
툴로 끌어 만드는 'QR 코드' 그래픽을 만들어 줘. 인스펙터에서 주소(글)와 색을 바꿀 수 있게.
render 는 순수 함수로, 외부 라이브러리 없이 QR 을 직접 계산해. 다 되면 shot 으로 확인해 줘.
인스펙터 칸은 test.mjs 에서 p.inspect 로 바꿔 보고, 개체를 고른 채 shot --ui 로 손잡이 자리도 확인해.

잘 되는 요령:

• 한 번에 하나씩. 큰 플러그인은 "먼저 매니페스트와 빈 명령만", "다음에 시험", … 처럼 나눠 시킨다.
• 확인을 시킨다. "check 오류 0, node test.mjs 통과, tools.mjs test 통과, shot 그림 확인까지 하고 끝났다고 말해" — AGENTS.md 에도 있지만 말해 두면 확실하다.
• API 가 궁금하면 문서를 읽게 한다. "API.md §9 를 읽고 tx.set 으로 바꿀 수 있는 속성을 알려 줘" — SDK 폴더에 API.md·README.md 가 있다(영어판은 en/).
• 오류는 그대로 붙여 넣는다. 브라우저에서 이상한 것을 보면 무엇을 눌렀고 무엇이 보였는지 적어 준다. 편집기 › 플러그인 메뉴 › 로그 내용도 도움이 된다.

12. 사람이 할 일

에이전트가 대부분 혼자 하지만, 이것은 사람이 한다.

1. 눈으로 확인 — 에이전트가 띄운 샌드박스 편집기(브라우저)에서 직접 눌러 본다. 마우스로 끄는 툴, 인스펙터 필드, 패널 화면은 사람이 봐야 한다. 에이전트도 미리 볼 수 있다 — 인스펙터 값 바꾸기는 모의 편집기의 p.inspect, 손잡이 자리는 shot --ui, 패널 html 은 podolay-ui-stub.js 로 Playwright 에서(개발자 안내 §8.8).
2. 개발자 신청 — 포털 › 내 정보 › 개발자에서 신청한다. 승인되어야 내 문서에서 개발 모드로 시험하고 올릴 수 있다(샌드박스 시험은 신청 없이 된다).
3. 올리기 — node ../podolay-plugin-sdk-<판>/tools.mjs pack . 이 만든 zip 을 포털 › 개발자 › 판 올리기 로 올리고 검수 요청. 올리기 전에 매니페스트의 version 을 올렸는지 본다. 사용법·예제(help, API §3.8)도 함께 준다면 — 매뉴얼(docs/*.md)·예제 파일(samples/)은 에이전트가 써도 되지만, 예제 레이아웃은 사람이 만든다: 레이아웃을 공유(받는 사람 없이)로 내 '공유' 폴더에 사본을 만들고 그 id 를 에이전트에게 알려 help.layouts 에 넣게 한다.
4. 새 SDK — dev·check 가 "새 SDK 가 나왔습니다" 라고 알리면, 새 zip 을 지금 SDK 폴더 옆(작업 폴더) 에 풀고 새 SDK 폴더의 tools.mjs 로 플러그인 폴더에서 node ../podolay-plugin-sdk-<새 판>/tools.mjs upgrade . 를 돌린다(에이전트 지침·시험 import 의 SDK 경로도 새 폴더로 바뀐다). 받을 주소·명령은 개발자 안내 §8.9.1 과 플러그인 폴더 AGENTS.md 의 업그레이드 절에 그대로 적혀 있다 — 에이전트에게 "SDK 를 업그레이드해 줘" 라고 해도 된다.

13. 문제가 생기면

더 자세한 개발 흐름은 개발자 안내, 모든 API 는 API 레퍼런스 에 있다.