워드프레스 공식 'agent-skills': AI의 구텐베르크 블록 에러와 보안 결함을 고치는 전용 가이드

워드프레스(WordPress) 팀이 Claude Code, Codex 등 AI 코딩 어시스턴트를 위한 공식 지침서 저장소인 'WordPress/agent-skills'를 깃허브(GitHub)에 공개했습니다. 2,200개의 스타(Star)를 기록하며 오픈소스 생태계의 주목을 받고 있는 이 저장소는 코딩 에이전트가 워드프레스의 최신 아키텍처 규격을 정확히 학습하고, 실무 개발 시 반복되던 블록 에러와 보안 취약점을 예방할 수 있도록 설계된 모듈형 스킬 컬렉션입니다.

이미지 출처: X (@sexyguy)

최근 터미널 기반 코딩 에이전트와 LLM을 워드프레스 테마나 플러그인 개발에 활용하는 개발자가 늘어났으나, 실제 현장에서는 모델의 부정확한 코드 생성으로 인한 작업 지연이 잦았습니다. 모델의 사전 학습 데이터에 구텐베르크(Gutenberg) 이전의 레거시 패턴이 포함되어 있어 구형 방식으로 코드를 짜거나, 블록 속성 변경 시 필수적인 과거 버전 호환 처리를 생략하여 에디터 화면에서 '이 블록은 올바르지 않습니다'라는 에러를 일으키는 문제가 대표적이었습니다. 워드프레스 팀의 공식 agent-skills는 이러한 AI 모델의 잘못된 코딩 버릇을 교정하고 최신 개발 표준을 직접 주입하는 명문화된 지침을 제공합니다.

구텐베르크 블록 파손과 '유효하지 않은 블록' 에러를 해결하는 규칙

워드프레스 블록 에디터 환경에서 AI 코딩 도구가 흔하게 일으키는 문제는 블록 유효성 검사 실패입니다.

구텐베르크 에디터는 포스트가 로드될 때 저장된 블록 마크업과 블록 정의를 대조하여 검증합니다. 만약 기존 블록을 수정하면서 과거 버전과의 호환성 처리(마이그레이션)를 빼먹거나 구형 코드가 생성되면 유효성 검사에 실패해 에디터에서 블록이 깨져버립니다.

• 최신 블록 표준 규격 준수: 구텐베르크 이전의 구형 작성 방식 대신 최신 워드프레스 블록 생성 표준과 구조를 따르도록 체크리스트와 예시 코드를 제공합니다.
• 블록 마이그레이션 및 하위 호환성 보장: 기존 블록의 정의나 속성을 수정할 때 과거 버전과의 불일치 경고를 방지할 수 있도록 마이그레이션 처리 지침을 명시합니다.

이를 통해 코딩 에이전트가 생성한 블록 컴포넌트가 실제 워드프레스 관리자 에디터에서 오류 없이 렌더링되고 편집 상태를 유지할 수 있도록 돕습니다.

프로젝트 식별부터 보안·자동화까지 10여 개 모듈형 스킬 구성

'WordPress/agent-skills'는 단일한 프롬프트 파일이 아니라 개발 영역별로 분리된 10여 개 이상의 모듈형 스킬로 구성되어 있습니다.

에이전트가 작업 대상 디렉토리를 탐색할 때 현재 작업 중인 워드프레스 프로젝트의 종류를 스스로 구분하고, 그에 맞는 전용 지침을 호출하도록 설계되었습니다.

• 플러그인 보안 수칙 강제: 플러그인을 제작할 때 워드프레스 개발자가 필수적으로 챙겨야 하는 사용자 권한 체크와 외부 입력값 검증 등 핵심 보안 규칙을 코드 생성 시 기본으로 반영하도록 지시합니다.
• REST API 권한 처리 명문화: 프로그램 간 데이터를 주고받는 REST API 엔드포인트를 생성할 때 필수적인 권한 검사 항목을 따로 다루어, 보안 누락 없는 안전한 인터페이스를 구축하도록 돕습니다.
• 반복 작업 자동화 명령어: 명령어로 반복 작업 자동화하는 규칙을 포함하여 실무 작업 효율을 높입니다.

'AI 작성 → 인간 감수 → AI 교육' 파이프라인과 실무 적용 시 유의점

이번 지침서 저장소의 제작 방식 또한 독특한 엔지니어링 접근을 보여줍니다. 워드프레스 공식 문서를 기반으로 AI 모델(Codex)이 1차 규칙 초안을 작성한 뒤, 인간 기여자들이 이를 정밀하게 검토하고 교정하여 다시 AI 에이전트를 교육하는 선순환 파이프라인으로 완성되었습니다.

실무 프로젝트에 도입할 때는 다음과 같은 환경적 특성과 한계점을 숙지해야 합니다.

• 에이전트 런타임 환경: Claude Code, Codex 등 Agent Skills 규격이나 컨텍스트 확장을 지원하는 코딩 에이전트 환경에서 직접 동작하며, 일반 웹 챗봇 환경에서는 스킬 문서를 프롬프트에 수동으로 주입해야 합니다.
• 초기 공개 단계의 엣지 케이스: 현재 저장소는 2,200개의 스타를 기록하고 있으나, 공개된 첫 버전인 만큼 실무 적용 중 발생하는 세부 오류와 엣지 케이스는 사용자들의 피드백을 바탕으로 지속 보완되는 단계입니다.
• 개발자의 최종 검증 책임: agent-skills가 표준 보안 수칙과 블록 구조를 강제하더라도, 복잡한 커스텀 DB 쿼리나 외부 통합 로직에 대한 최종 검토와 검증 책임은 여전히 개발자에게 있습니다.

워드프레스 기반의 제품을 제작하거나 사이트를 유지보수하면서 AI 코딩 어시스턴트를 도입하려는 엔지니어라면, 에이전트의 오작동 비용을 줄이기 위해 저장소의 스킬 구성을 검토해볼 가치가 충분합니다.

출처

• GitHub: WordPress/agent-skills
• X (@sexyguy): 워드프레스 agent-skills 소개 및 실무 적용 후기