# AI 네이티브 블록 개발

파일을 사용하고 빌드 단계가 없습니다. 에이전트가 잘 다루는 방식입니다.

[문서 읽기](https://blockstudio.dev/ko/docs/dev/ai/)

코딩 에이전트가 단일 프롬프트로 사용자 지정 블록 10개와 페이지 6개를 갖춘 완전한 WordPress 사이트를 만드는 과정을 담은 무음 화면 녹화입니다.

## 블록을 설명하면 블록이 만들어집니다

AI 코딩 에이전트는 프롬프트 하나로 블록, 페이지, 패턴의 기본 구조를 만들 수 있습니다. GUI도 데이터베이스도 필요 없이 파일만 있으면 됩니다.

~/starter-theme

❯ 가격 블록을 만들고, 세 가지 요금제와 월간/연간 전환 기능, 각 요금제의 CTA를 추가하세요.

✓ 생성일 pricing/block.json

✓ 생성일 pricing/index.php

✓ 생성일 pricing/style.css

❯ 이제 히어로와 FAQ 섹션이 있는 가격 페이지를 만드세요.

✓ 생성일 pages/pricing/page.json

✓ 생성일 pages/pricing/index.php

파일

blockstudio/

├── pricing/ 새 항목

├── block.json

├── index.php

└── style.css

pages/

├── pricing/ 새 항목

├── page.json

└── index.php

## 모든 것이 파일 기반

블록, 페이지, 패턴 및 확장 기능은 JSON 설정 파일과 템플릿이 들어 있는 디렉터리입니다. 에이전트가 파일을 그대로 읽고 쓸 수 있습니다.

## 데이터베이스 설정 불필요

클릭해서 이동해야 하는 관리 패널이 없습니다. 모든 설정은 JSON 키이므로 에이전트가 브라우저 없이 라이브러리의 기본 구조를 만들 수 있습니다.

## 예측 가능한 구조

모든 블록은 같은 규칙을 따릅니다. block.json, 템플릿, 선택적 스타일이 전부입니다. 규칙을 한 번만 익히면 됩니다.

## 추측이 아닌 맥락

문서의 간결한 색인과 전체 문서를 원하는 도구를 위한 전문을 제공합니다.

### 에이전트가 먼저 읽는 색인

`blockstudio-llm.txt` 에는 모든 문서가 경로, 소스 파일, 용도와 함께 한 번씩 나열되며, 각 문서가 담당하는 설정, 훅, PHP 함수 및 CLI 명령도 표시됩니다. 약 11k 토큰 분량이라 에이전트가 전체를 읽은 다음 필요한 페이지만 엽니다.

`blockstudio-llm-full.txt` 에는 모든 문서와 JSON 스키마가 약 169k 토큰 분량의 단일 파일로 들어 있어 전체 문서를 원하는 도구에 적합합니다. `ai.enableContextGeneration` 를 켜면 사이트에서 두 파일을 모두 제공합니다.

[AI 통합 문서](https://blockstudio.dev/ko/docs/dev/ai/)

blockstudio-llm.txt

```
# Blockstudio documentation index

This is the primary context file for coding assistants. It is an index, not
the documentation itself. Each entry names one document, what it is for, and
the identifiers that document owns. Read this index, then open only the
document you need.

Every document is addressable two ways: as a URL on https://blockstudio.dev,
and as a Markdown file in the Blockstudio repository. The full text of every
document and schema is also available in one file at /blockstudio-llm-full.txt
for tools that want everything at once.
```

## 프로젝트용 계약

문서는 Blockstudio을 설명합니다. AGENTS.md은 에이전트가 변경하려는 프로젝트를 설명합니다.

### 명령 하나로 AGENTS.md 작성

`vendor/bin/blockstudio-agents` 는 실행 중인 프로젝트를 설명합니다. 프로젝트에 포함된 내용, `blockstudio.json` 가 활성화하는 기능, 분석에서 거부되는 항목, 적용되는 명령을 안내합니다.

모든 내용은 파일, 설정 또는 선택한 분석 프리셋에서 가져옵니다. 다시 생성해도 직접 작성한 메모는 유지되며, 계약 내용이 오래되면 `--check` 가 실패합니다.

[프로젝트 계약](https://blockstudio.dev/ko/docs/dev/phpstan/#project-contract-for-coding-agents)

AGENTS.md

```
# Blockstudio contract for Acme

## Project

- Kind: WordPress theme `Acme`.
- Configuration: `blockstudio.json`.
- Analysis preset: `extreme-theme`.

## What this project contains

- Blocks: 1 in `blockstudio`.
- Pages: 1 in `pages`.
- Block namespaces: `acme`.
- Block templates are written in PHP.
```

## 커밋 전에 오류 발견

각각 이전 프리셋의 기능을 모두 포함하는 네 가지 분석 프리셋과 모든 커밋에서 실행되는 훅입니다.

### block.json을 이해하는 분석

`blockstudio/phpstan` 프리셋은 블록, 페이지 및 설정을 읽습니다. `block.json` 에 선언되지 않은 필드를 템플릿에서 읽거나 이스케이프하지 않고 출력하면 분석에 실패합니다.

템플릿은 옆에 있는 `block.json` 에서 입력된 `$a` 을(를) 읽습니다. 각 필드 유형에는 구체적인 PHP 유형이 있으며, `Db::get()` 은(는) `db.php` 에 맞는 형태의 레코드를 반환합니다. 설정 경로나 후크 이름의 철자가 틀리면 가장 가까운 실제 이름을 제안하며 오류를 표시합니다.

`githooks.commit` 을 설정하고 `vendor/bin/blockstudio-githooks sync` 을 실행하세요. 관리되는 사전 커밋 훅에서 동일한 분석을 실행하므로 문제가 있는 블록은 커밋되지 않습니다.

[분석 프리셋](https://blockstudio.dev/ko/docs/dev/phpstan/#analysis-presets)

blockstudio.json

```
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": { "preset": "extreme-theme" },
  "githooks": { "commit": true }
}
```

## [base](https://blockstudio.dev/ko/docs/dev/phpstan/#analysis-presets)

템플릿이 읽는 모든 $a 키는 block.json에 정의되어 있습니다. 훅, 설정 경로, 블록 태그가 실제로 존재합니다.

## [theme](https://blockstudio.dev/ko/docs/dev/phpstan/#analysis-presets)

테마 헤더, 선언된 에셋, %selector% 범위 지정, 필드 기본값 및 반복 필드 제한.

## [extreme-theme](https://blockstudio.dev/ko/docs/dev/phpstan/#analysis-presets)

PHPStan 최대값, 이스케이프된 출력, 셸 명령 실행 금지, 유효한 Tailwind 클래스 및 깔끔한 JavaScript.

## [wordpress-render](https://blockstudio.dev/ko/docs/dev/phpstan/#live-wordpress-rendering)

Extreme 테마와 사용자가 제공하는 라이브 WordPress 렌더 프로브를 사용합니다. 셸 없이 실행되며 렌더링에 실패하면 문제로 보고됩니다.

## [Twig, Blade 및 스크립트](https://blockstudio.dev/ko/docs/dev/phpstan/#what-it-checks)

Twig, Blade 및 블록 태그를 동일한 필드와 대조해 검사합니다. Extreme 계층은 마크업과 저장소를 기준으로 JavaScript 및 Interactivity 지시문도 읽습니다.

## [기존 프로젝트](https://blockstudio.dev/ko/docs/dev/phpstan/#adopting-analysis-on-an-existing-project)

PHPStan 기준선을 사용하면 기존 문제는 보류하고 새 코드는 전체 프리셋을 충족하도록 할 수 있습니다. blockstudioScanRoots는 루트 밖의 블록 라이브러리를 읽고, 함께 제공되는 스텁은 공개 API의 타입을 지정합니다.

## PHP에서 인벤토리 확인 및 렌더링

몇 가지 호출만으로 에이전트가 프로젝트에 등록된 항목을 확인하고, 원하는 부분을 렌더링하며, 저장된 데이터를 살펴볼 수 있습니다.

### 프로젝트에 묻고 답변 렌더링하기

`Canvas::inventory()` 은 프로젝트에 등록된 모든 페이지, 블록, 패턴, 사이트 편집기 템플릿, 템플릿 파트 및 UI 예제를 렌더링 없이 반환합니다.

`Render::document()` 은 이 항목을 사용된 에셋만 포함하는 완전한 HTML 문서로 렌더링하므로 에이전트가 편집기 밖에서 결과를 확인할 수 있습니다.

`Canvas::documents()` 은(는) 선택한 레코드만 정확히 렌더링합니다. `Render::composition()` 및 `Render::content()` 은(는) 중첩 선언이나 직렬화된 블록 콘텐츠를 HTML(으)로 반환하며, `Ui::inventory()` 및 `Ui::examples()` 은(는) 번들에 포함된 컴포넌트 계열을 렌더링 가능한 선언 하나씩 나열합니다.

블록 하나에 대해 `bs_block_fields()`, `bs_block_extension_fields()`, `bs_block_values()`, `bs_block_assets()` 은(는) 렌더링 없이 해당 블록의 필드, 값, 에셋을 반환하고, `bs_validate_block()` 은(는) 저장된 속성을 저장 전에 검사합니다.

[프로그래밍 방식 렌더링](https://blockstudio.dev/ko/docs/blocks/rendering/#structured-compositions-and-complete-documents)

inspect.php

```
use Blockstudio\Canvas;
use Blockstudio\Render;

$project = Canvas::inventory(['blocks' => true]);

foreach ($project['inventory']['blocks'] as $block) {
  echo $block['name'] . "\n";
}

$doc = Render::document(
  ['name' => 'acme/hero', 'data' => ['heading' => 'Hello']],
  ['title' => 'Hero preview']
);

file_put_contents('hero.html', $doc['html']);
```

## 페이지당 토큰을 절반 이하로

에이전트는 일반 HTML을 작성합니다. 동기화 시 Blockstudio가 이를 직렬화된 WordPress 블록 마크업으로 변환해 생성할 내용과 실수를 줄입니다.

### Blockstudio

에이전트가 작성하는 내용

약 135 토큰

index.php

```
<h1>Build Websites That Convert</h1>
<p>The all-in-one platform for creating
beautiful, high-performance landing pages.</p>

<block name="core/columns">
  <block name="core/column">
    <h3>Lightning Fast</h3>
    <p>Pages load in under one second.</p>
  </block>
  <block name="core/column">
    <h3>Easy to Use</h3>
    <p>No technical skills required.</p>
  </block>
  <block name="core/column">
    <h3>SEO Optimized</h3>
    <p>Built-in best practices from day one.</p>
  </block>
</block>

<img src="/dashboard.jpg" alt="Dashboard" />
```

### WordPress

파서가 이를 위해 작성하는 내용

약 310 토큰

post_content

```
<!-- wp:heading {"level":1} -->
<h1 class="wp-block-heading">Build Websites That Convert</h1>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p>The all-in-one platform for creating
beautiful, high-performance landing pages.</p>
<!-- /wp:paragraph -->
<!-- wp:columns -->
<div class="wp-block-columns">
  <!-- wp:column -->
  <div class="wp-block-column">
    <!-- wp:heading {"level":3} -->
    <h3 class="wp-block-heading">Lightning Fast</h3>
    <!-- /wp:heading -->
    <!-- wp:paragraph -->
    <p>Pages load in under one second.</p>
    <!-- /wp:paragraph -->
  </div>
  <!-- /wp:column -->
  <!-- wp:column -->
  <div class="wp-block-column">
    <!-- wp:heading {"level":3} -->
    <h3 class="wp-block-heading">Easy to Use</h3>
    <!-- /wp:heading -->
    <!-- wp:paragraph -->
    <p>No technical skills required.</p>
    <!-- /wp:paragraph -->
  </div>
  <!-- /wp:column -->
  <!-- wp:column -->
  <div class="wp-block-column">
    <!-- wp:heading {"level":3} -->
    <h3 class="wp-block-heading">SEO Optimized</h3>
    <!-- /wp:heading -->
    <!-- wp:paragraph -->
    <p>Built-in best practices from day one.</p>
    <!-- /wp:paragraph -->
  </div>
  <!-- /wp:column -->
</div>
<!-- /wp:columns -->
<!-- wp:image {"alt":"Dashboard","url":"/dashboard.jpg"} -->
<figure class="wp-block-image"><img src="/dashboard.jpg" alt="Dashboard"/></figure>
<!-- /wp:image -->
```

위의 두 패널을 기준으로 측정했습니다. HTML의 540자와 기본 파서가 이를 위해 작성하는 블록 마크업 1,233자를 비교하고, 토큰당 일반적인 추정치인 4자로 나눴습니다. 마크업은 읽기 쉽도록 줄바꿈을 추가해 표시합니다.

## 생성할 출력 감소

에이전트는 블록 구분자, 생성된 클래스 또는 래퍼 마크업 없이 HTML을 작성합니다.

## 실수할 부분 감소

파서는 더 단순한 입력으로 유효한 블록 출력을 보장합니다.

## 더 빠르고 저렴하게

출력 토큰이 줄어들면 응답이 빨라지고 모델 비용이 낮아집니다.

## 모든 AI 코딩 도구에서 작동

파일을 읽고 쓸 수 있는 에이전트라면 어떤 것이든 Blockstudio와 바로 사용할 수 있습니다.

Claude Code

Codex CLI

Gemini CLI

Cursor

Windsurf

Amp

## AI 워크플로우에 맞게 설계

블록, 페이지, 패턴, 설정이 모두 에이전트가 읽고 쓰고 수정할 수 있는 파일입니다.

## 블록당 파일 두 개

JSON 설정 파일과 템플릿이 블록의 전부입니다. 표면적이 작아 첫 생성부터 안정적으로 만들 수 있습니다.

## 27개 필드 유형

텍스트, 파일, 반복 필드, 색상, 날짜 등을 JSON에서 정의하세요. 선택 항목은 게시물, 용어, 사용자 데이터에서 채워집니다.

## JSON 스키마 유효성 검사

모든 설정에는 스키마가 있어 에이전트에 정확한 규칙을 알려주고 오류를 즉시 찾아냅니다.

## 자동 등록

파일을 디렉터리에 넣으면 별도의 설정 목록 없이 블록이 자동으로 등록됩니다.

## 캔버스 개요

확대 및 축소할 수 있는 하나의 보기에서 모든 관리 페이지를 확인하거나, 모든 블록을 기본값과 함께 확인하세요.

## 라이브 캔버스

라이브 모드는 저장 후 약 1초 뒤 Server-Sent Events를 통해 영향을 받은 아트보드를 새로 고칩니다. 아트보드 하나에 초점을 맞추려면 레이블을 클릭하세요.

## Tailwind 기본 제공

TailwindPHP가 각 페이지에서 사용하는 클래스를 컴파일하므로 Node 설정이 필요 없습니다.

## Element Grabber

요소의 템플릿 경로와 마크업을 복사해 에이전트에 즉시 맥락을 제공하세요.

## HTML에서 블록으로

페이지와 패턴은 기본 WordPress 블록으로 변환되는 일반 파일입니다.

## 렌더링 스모크 테스트

wp bs blocks render는 페이지처럼 모든 블록을 렌더링하며 템플릿에서 알림, 경고 또는 오류가 발생하면 1로 종료합니다.

## 저장된 콘텐츠 검사

wp bs blocks validate는 글의 저장된 필드를 검사하고, pages sync는 블록이 저장하지만 렌더링하지 않는 속성을 경고합니다.

## 터미널에서 검사

wp bs로 설정, 사용자 지정 필드, 에셋을 나열하고 wp bs tailwind compile 또는 wp bs scss compile로 코드 조각이나 파일을 컴파일하세요.

Plus

## 공식 확장 키트

프리미엄 사이트 템플릿, AI 시스템 지침, 비공개 Discord 커뮤니티를 제공합니다. 한 번 구매하면 업데이트를 평생 받을 수 있습니다.

- 500개 이상의 사이트 템플릿
- AI 시스템 지침
- 평생 업데이트
- 비공개 Discord 커뮤니티

[Plus 이용하기](https://blockstudio.dev/ko/plus/)
