개선 가이드
개선 가이드 수명주기, Plan.md 실행, write target (live/shadow/local), 스토어 쓰기 되돌리기까지 설명합니다.
개선 가이드란
개선 가이드는 AEKO가 추적·진단 결과를 기반으로 자동 생성하는 "실행 단위"입니다. 카드 한 장에 무엇을 고칠지, 왜 고쳐야 하는지, 어떻게 적용할지가 모두 들어 있습니다. 각 카드에는 카드 생성 시점에 템플릿으로부터 결정론적으로 렌더링된 Plan.md가 첨부되어, 클립보드 복사 → Claude에 붙여넣기만 하면 그대로 실행됩니다. 카드 생성 자체에는 LLM 호출이 일어나지 않으며, 실제 콘텐츠 작성은 Claude(Sonnet)가 Plan을 실행할 때 일어납니다.
왜 이 형태인가
일반적인 SEO 도구는 "개선해야 할 것" 목록만 줍니다. AEKO는 한 단계 더 가서, 각 항목을 Claude·Cursor·Codex가 그대로 실행할 수 있는 실행 계획으로 변환합니다. 사람은 검토하고 승인하는 역할만 합니다.
세 가지 트랙
개선 작업은 다음 세 흐름에서 확인할 수 있습니다.
1. 기술 및 상품 페이지 점검
/dashboard/improve/technical
사이트 구조와 판매 중인 상품 페이지의 AEO 신호를 확인합니다. 상품별 "AI로 개선" 버튼은 해당 상품을 인자로 Claude 작업을 엽니다.
2. 컨텐츠 최적화
/dashboard/improve/content
AI가 인용한 출처에서 브랜드명이 확인되는지 살펴보고, 확인된 채널 공백을 바탕으로 컨텐츠 아이디어를 제안합니다. 직접 아이디어를 만들고 AI로 전달하는 기존 흐름과 기록도 이 페이지에 있습니다.
3. Context — 고객 상황 입력
/dashboard/analyze/context
리뷰나 직접 입력으로 고객 상황을 저장합니다. 저장된 컨텍스트는 프롬프트 추적과 콘텐츠 생성 흐름에서 AI가 어떤 쇼퍼에게 답하는지 정하는 데 사용됩니다. 자세한 내용은 컨텍스트 가이드를 참고하세요.
가이드 수명주기
카드는 생성 즉시 ready로 시작합니다. 그 뒤에는 사용자가 완료 표시하거나 무시할 때 상태가 바뀝니다. 각 단계는 카드의 상태 뱃지로 표시됩니다.
| 상태 | 의미 |
|---|---|
| ready | 카드 생성 직후 기본 상태 — Plan.md가 즉시 렌더링됨. "복사" 또는 "Claude에서 실행" 버튼이 곧바로 활성화됩니다. |
| completed | 사용자가 완료 표시 — 결과물 저장됨, 감사 로그 기록 |
| failed | 렌더링 또는 후속 도구 실행 실패 — last_error 확인 후 재생성 |
| dismissed | 실행하지 않기로 결정 — 목록에서 숨김, 감사 로그에는 남음 |
기존 데이터에는 pending·generating_prose·in_progress 상태가 남아 있을 수 있습니다. 화면에는 그대로 표시되지만, 사용자가 선택하는 상태는 ready와 completed입니다 (API는 in_progress도 허용).
우선순위 뱃지
상태와 별개로 각 카드에는 critical / high / medium / low 우선순위가 붙습니다. critical은 회귀나 보안 영향, low는 마이크로 최적화입니다.
Plan.md와 Copy-for-AI
Plan.md는 단순한 작업 지시서가 아니라, 그 자체가 Claude·Codex·Cursor 안에서 즉시 실행 가능한 명령입니다. 헤더에 메타데이터(타겟 URL, 아티팩트 유형 등)가 있고, 본문은 정해진 템플릿에 카드 컨텍스트(제품, 저장된 컨텍스트, 금지어 등)를 끼워 넣어 만들어진 단계별 설명입니다.
실행 방법 2가지
- 복사: 클립보드에 명령어 복사 → 이미 열려 있는 Claude Desktop/Code에 Cmd/Ctrl+V로 붙여넣기
- Claude 웹에서 실행: claude.ai에 새 채팅을 열고 명령어를 자동 입력 — Enter만 누르면 aeko-mcp이 Plan을 실행
aeko-mcp이 자동으로 하는 것
MCP 도구 aeko_get_action_plan으로 Plan.md를 가져오고, 저장된 컨텍스트와 기존 PDP를 입력으로 적재한 뒤, 최종 결과물을 생성합니다. 작업이 끝나면 aeko_complete_action_item을 호출해 카드 상태가 자동으로 completed로 바뀝니다. (MCP 도구명은 API 호환을 위해 그대로 유지됩니다.)
상품 페이지 전달 방식 — 먼저 미리보기
상품 페이지 개선 작업은 항상 로컬 미리보기를 먼저 만듭니다. Plan.md의 write_target은 내부 실행 정보일 뿐, 스토어 변경에 대한 사용자 동의가 아닙니다. 미리보기를 확인한 다음 아래에서 실제로 지원되는 방식을 선택합니다.
| 선택 | 동작 |
|---|---|
| 미리보기만 유지 | 스토어를 바꾸지 않고 로컬 결과물만 보관합니다. |
| 비공개 초안 상품으로 저장 | 연결된 스토어가 실제 초안 생성 기능을 제공할 때만 표시됩니다. 일반 상품 업데이트를 초안처럼 부르지 않습니다. |
| 현재 상품 페이지에 적용 | 변경 전·후, 위험, 되돌리기 방법을 확인한 뒤 한 번 더 명확히 동의해야 적용됩니다. |
미리보기는 선택 사항이 아닙니다
현재 상품 페이지 적용을 선택해도 바로 쓰지 않습니다. AI가 정확한 변경 범위와 위험, 되돌리기 방법을 먼저 보여주고 별도 확인을 요청합니다. 취소하거나 답이 모호하면 미리보기만 유지합니다.
티어 게이팅
아티팩트마다 최소 플랜이 다릅니다. 백엔드의 ARTIFACT_TIER_REQUIRED 맵이 기준이며, AI를 통한 상품 페이지 개선과 컨텐츠 생성은 Pro 이상에서 사용할 수 있습니다.
| 기능 | 최소 티어 |
|---|---|
PDP HTML 리라이트 (pdp_html) | Pro |
제품 JSON-LD 생성 (json_ld) | Starter |
| 기술 점검 가이드 (llms.txt, robots.txt, technical_bundle) | Starter |
| 현재 상품 페이지 적용 (PDP 개선 작업) | Pro |
콘텐츠 변형 — 자체 블로그용 (own_store_markdown) | Pro |
콘텐츠 변형 — 외부 매체용 (external_media_markdown) | Pro |
JSON-LD와 기술 점검 가이드는 Starter에서 사용할 수 있습니다. 전체 한도는 구독 요금제 가이드를 참고하세요.
스토어 쓰기 되돌리기
현재 상품 페이지에 적용된 모든 변경은 스토어 쓰기 감사 로그에 자동 기록됩니다. 변경 이력 조회와 되돌리기는 AEKO 에이전트(MCP)를 통해 진행합니다 — Claude에서 aeko_list_store_writes로 이력을 확인하고 aeko_revert_store_write로 이전 상태로 복원합니다.
감사 로그에 남는 정보
- 실행자 (사용자 또는 MCP) + 타임스탬프
- 플랫폼 (Shopify, Cafe24) + 외부 제품 ID
- 오퍼레이션 (description, json_ld, tags, meta 등)
- 이전 값과 새 값의 전체 JSONB 스냅샷
- 상태 (성공/실패) + 되돌리기 참조 ID
주의
되돌리기는 AEKO가 직접 쓴 필드만 복원합니다. 그 사이에 스토어에서 직접 수정한 변경은 보존되지 않으니, 되돌리기 전에 라이브 페이지를 한 번 확인하세요.
End-to-End 예시
상품 페이지 개선 1건 실행하기
- 1.
/dashboard/improve/technical에서 개선할 제품 선택 - 2. 상품 행의 "AI로 개선"을 눌러 Claude 작업 열기
- 3. 플러그인이 이 상품의 기존 작업을 찾고, 없으면 새 작업을 하나 생성
- 4. Claude가 만든 상품 설명과 JSON-LD를 검토한 뒤 적용 여부 결정
- 5. 적용 후 기술 점검과 Measure에서 변화를 확인
AI로 개선을 사용하려면
AEKO 플러그인과 MCP 연결이 필요합니다. 연결 전에도 상품별 구조 점검 결과는 볼 수 있습니다. 설치 방법은 에이전트 설정 가이드를 참고하세요.