🌸이번 봄, AI 에이전트가 읽고 쓸 수 있는 WordPress 폼 플러그인을 만들었습니다

이 기사는 WordPress에 관한 이야기이지만, 본질은 "GUI 도구의 설정은 AI에게 보이지 않고, 코드는 AI에게 보인다"라는 설계 사상에 관한 이야기입니다. WordPress를 사용하지 않는 분들에게도 관련이 있다고 생각합니다.

🌸Zenn에서의 집필도 이번 봄에 시작했습니다.

AI를 사용한 개발에서, 이런 경험을 한 적이 없으신가요?

"Contact Form 7의 폼을 수정해줘"라고 부탁하면, AI는 길게 조작 절차를 설명하기 시작합니다. 스크린샷을 전달하고, 관리 화면의 어디를 열어서 어디를 클릭하고……라는 설명의 주고받음만으로도 대량의 토큰 (Token)이 소비됩니다.

게다가 출력되는 것은 코드가 아니라 "절차서". 직접 조작해야만 합니다.

AI의 토큰을 대량으로 사용하고, 결국 자신이 직접 손을 움직인다. 이것은 효율이 너무 나쁩니다.

이 문제를 근본적으로 해결하기 위해, 이번 봄, WordPress 폼 플러그인을 제로 베이스에서 설계·공개했습니다. 결론부터 말하자면, 폼을 PHP 배열로 만드는 것만으로도 AI와의 상호작용에 필요한 토큰이 구조적으로 줄어듭니다.

발상의 기점: 폼이 코드가 아니라는 것이 문제였다

GUI 폼 빌더 (Form Builder)에는 공통된 문제가 있습니다.

폼이 데이터베이스 (Database)에 들어있다.

이것이 모든 문제의 근본입니다.

• Git으로 관리할 수 없다
• 배포하면 폼이 사라졌다
• 운영 환경과 개발 환경의 설정이 어긋났다
• AI가 직접 건드릴 수 없다

해결책은 심플했습니다.

설계: PHP 배열로 폼을 정의한다

HXFE — Code-First Forms 에서는, 폼을 PHP 배열로서 정의합니다.

add_filter( 'hxfe_schemas', function( $schemas ) {
$schemas['contact'] = [
'id' => 'contact',
...

숏코드 (Shortcode) [hxfe_form id="contact"]

를 두는 것만으로 작동합니다.

프론트엔드 (Frontend)는 htmx (HTML의 속성만으로 AJAX 통신을 기술할 수 있는 경량 라이브러리)가 담당합니다. React의 빌드 환경은 필요 없습니다. HXFE 는 htmx Form Engine의 머릿글자입니다.

이 배열이 functions.php에 들어간 순간, 폼은 코드가 됩니다.

이것은 말하자면 뺄셈의 설계입니다. 데이터베이스를 사용하지 않는다. 빌드 환경을 가져오지 않는다. GUI를 만들지 않는다. 뺀 결과로서 남은 것이 PHP 배열과 htmx라는 최소 구성이었습니다.

설계의 주안점 ①: 하나의 스키마가 4개의 UI로 변신한다

HXFE에서 가장 마음에 드는 설계가 step_mode입니다.

동일한 fields 정의 그대로, 한 줄만 추가하면 UI가 바뀝니다.

// 동일한 필드 정의로부터, step_mode의 한 줄로 UI가 바뀜
add_filter( 'hxfe_schemas', function( $schemas ) {
// 공용 필드 정의
...

일반 폼

챗봇 모드

(step_mode: 'chatbot'를 추가)

chatbot 모드 (

)

1문 1답 모드

(step_mode: 'one_by_one'로 변경)

1문 1답 모드 (

)

필드를 다시 쓸 필요가 없습니다. 스키마는 하나. UI만 바뀝니다.

이 설계는 AI 에이전트 (AI Agent)와의 궁합에도 효과적입니다. "이 폼을 챗봇 형식으로 바꿔줘"라고 부탁했을 때, AI가 변경해야 할 부분이 step_mode의 한 줄뿐이라는 것을 명확히 알 수 있습니다.

설계의 주안점 ②: 완료 화면을 답변에 따라 전환하는 진단 모드

complete_html_rules를 사용하면, 답변에 따라 완료 화면의 HTML을 전환할 수 있습니다.

$schemas['diagnosis'] = [
'id' => 'diagnosis',
'to' => '', // 메일 전송 없음 → 순수한 진단 모드
...

데이터베이스 미사용. JavaScript 미사용. PHP 배열만으로 "답변에 따른 진단 결과"가 나옵니다.

AI에게 진단 로직을 쓰게 할 때, 이 설계가 빛을 발합니다.

필드 정의와 결과 패턴을 AI에게 전달하고 "complete_html_rules를 작성해줘"라고 부탁하는 것만으로, 조건 분기 코드가 돌아옵니다. GUI 빌더에서는 불가능한 의뢰입니다.

설계의 주안점 ③: AI가 읽기 위한 문서를 동봉한다

HXFE 설계에서 가장 공을 들인 부분 중 하나는 AI 에이전트용 문서 동봉입니다.

hxfe-code-first-forms/
├── llms.txt ← AI 에이전트용 API 사양 요약
├── ai-reference.md ← 스키마 키 목록·사용 예시·lint 경고·주의 사항
...

Claude, Cursor, GitHub Copilot, Codex와 같은 AI 코딩 도구가 이것들을 읽음으로써, HXFE의 스키마 사양을 파악한 상태에서 코드를 생성해 줍니다.

PHP를 쓸 줄 몰라도 문제없습니다. AI 에이전트에게 "문의 양식을 만들어줘"라고 일본어로 전달하는 것만으로, 동작하는 스키마를 생성해 줍니다.

이는 "AI가 사용하는 것을 전제로 설계한 플러그인"이라는 선언이기도 합니다.

AI 에이전트와의 협업 비용 비교

폼이 코드가 됨으로써 AI와의 상호작용이 어떻게 변하는가.

GUI 빌더 (CF7, WPForms)의 경우:

인간의 입력:
"문의 양식에 전화번호 필드를 추가해줘.
Contact Form 7을 사용하고 있어.
...

입력: 상황 설명 + 스크린샷 → 대량의 토큰 (Token)

출력: 조작 절차서 → 대량의 토큰 (Token)

실제 작업: 인간이 수행

HXFE의 경우:

인간의 입력:
"이 스키마에 전화번호 필드를 추가해줘"
+ PHP 배열 (수십 줄)
...

입력: PHP 배열만 전달 → 적은 토큰 (Token)

출력: 차분이 명확한 한 줄의 코드 → 적은 토큰 (Token)

실제 작업: 복사 및 붙여넣기만 수행

토큰 비용의 차이는 구조적으로 발생합니다. GUI 빌더에서는 "상황 설명"만으로도 대량의 토큰이 필요합니다. PHP 배열이라면 스키마를 그대로 전달하면 됩니다.

더 중요한 것은 출력의 질입니다. GUI 빌더에 대한 지시는 "절차서"가 돌아옵니다. PHP 배열에 대한 지시는 "코드"가 돌아옵니다.

이번 봄에 시작한 것: AI 에이전트와의 새로운 개발 스타일

플러그인을 공개하며 깨달은 점이 있습니다.

AI 에이전트와 함께 개발할 때 가장 중요한 것은 무엇인가.

여담: AI 서비스가 바뀌어도 폼은 계속 작동한다

최근 AI를 둘러싼 환경은 급격하게 변화하고 있습니다.

2026년 6월, Cursor가 SpaceX에 600억 달러로 인수된다는 발표가 있었습니다. X와 마찬가지로 Elon Musk의 산하로 들어감에 따라, 플랜이나 방침에 큰 변경이 발생할 가능성이 있습니다. AI 도구의 소유자·운영자가 바뀜으로써, 지금까지 당연하게 사용해 왔던 환경이 갑자기 변할 리스크는 결코 남의 일이 아닙니다.

HXFE는 이 점에서도 안심할 수 있는 설계입니다. 폼의 정의는 PHP 코드이므로, AI 서비스가 바뀌어도 전혀 영향을 받지 않습니다. Claude에서 ChatGPT로 갈아타더라도, Cursor에서 VS Code로 돌아가더라도 PHP 배열은 그대로 전달할 수 있습니다.

이 설계 사상은 폼 이외에도 확장됩니다.

• 설정은 코드로 관리 (DB가 아닌)
• 문서는 AI가 읽을 수 있는 형태로 작성 (llms.txt, ai-reference.md)
• 에러 로그도 텍스트 파일에 작성 (AI에게 전달하기 쉽게)

이번 봄에 시작한 것은 플러그인 개발만이 아니었습니다. AI 에이전트와 함께 개발하는 것을 전제로 한, 새로운 설계 스타일을 시작한 봄이었습니다.

현재의 HXFE

얼마 전 (2026년 6월), HXFE — Code-First Forms를 WordPress.org에 공개했습니다.

• 15종의 필드 타입
• 4가지 UI 모드 (일반, 스텝, 1문 1답, 챗봇)
• 조건 분기, Webhook, SMTP 내장, 파일 업로드
• 에러 로그 (v1.4.0~, DB를 사용하지 않고 파일에 기록)
• AI용 문서 동봉 (llms.txt / ai-reference.md / CLAUDE.md)
• 데이터베이스 미사용, 쿠키 미사용, 무료, 오픈 소스

GitHub 리포지토리에서 소스 코드를 공개하고 있습니다. 피드백과 Issue를 환영합니다.

Discussion