Improvement Guides
Lifecycle of an improvement guide, Plan.md execution, write targets (live/shadow/local), and revert.
개선 가이드란
개선 가이드는 AEKO가 추적·진단 결과를 기반으로 자동 생성하는 "실행 단위"입니다. 카드 한 장에 무엇을 고칠지, 왜 고쳐야 하는지, 어떻게 적용할지가 모두 들어 있습니다. 각 카드에는 카드 생성 시점에 템플릿으로부터 결정론적으로 렌더링된 Plan.md가 첨부되어, 클립보드 복사 → Claude에 붙여넣기만 하면 그대로 실행됩니다. 카드 생성 자체에는 LLM 호출이 일어나지 않으며, 실제 콘텐츠 작성은 Claude(Sonnet)가 Plan을 실행할 때 일어납니다.
왜 이 형태인가
일반적인 SEO 도구는 "개선해야 할 것" 목록만 줍니다. AEKO는 한 단계 더 가서, 각 항목을 Claude·Cursor·Codex가 그대로 실행할 수 있는 실행 계획으로 변환합니다. 사람은 검토하고 승인하는 역할만 합니다.
세 가지 트랙
개선 가이드는 Improve 섹션의 세 페이지에 자동으로 분배됩니다.
1. Technical Checkup — 사이트 전체 단위
/dashboard/improve/technical
llms.txt, robots.txt, sitemap, 홈페이지 JSON-LD 같은 사이트 레벨 항목. 한 번 적용하면 모든 페이지에 영향이 갑니다. 아티팩트 유형: llms_txt, robots_txt_patch, technical_bundle.
2. PDP Fixes — 제품 페이지 단위
/dashboard/improve/pdp
개별 제품 페이지의 설명·메타·JSON-LD 리라이트와, 같은 제품을 자체 블로그·외부 미디어용으로 변환하는 콘텐츠 변형 가이드를 생성합니다. 아티팩트 유형: pdp_html, json_ld, own_store_markdown, external_media_markdown.
3. Brand Settings — 컨텍스트 입력
/dashboard/improve/brand
다른 두 트랙의 입력 — 브랜드 킷·ICP가 채워지지 않으면 PDP/Tech 가이드가 일반적인 출력을 내놓습니다. 이 페이지는 가이드 카드를 생성하지 않고, 다른 카드의 컨텍스트를 제공합니다. 자세한 내용은 브랜드 킷 & 페르소나 가이드를 참고하세요.
가이드 수명주기
카드는 생성 즉시 ready로 시작합니다. 그 뒤에는 사용자가 완료 표시하거나 무시할 때 상태가 바뀝니다. 각 단계는 카드의 상태 뱃지로 표시됩니다.
| 상태 | 의미 |
|---|---|
| ready | 카드 생성 직후 기본 상태 — Plan.md가 즉시 렌더링됨. "복사" 또는 "Claude에서 실행" 버튼이 곧바로 활성화됩니다. |
| completed | 사용자가 완료 표시 — 결과물 저장됨, 감사 로그 기록 |
| failed | 렌더링 또는 후속 도구 실행 실패 — last_error 확인 후 재생성 |
| dismissed | 실행하지 않기로 결정 — 목록에서 숨김, 감사 로그에는 남음 |
DB enum에는 pending·generating_prose가 남아 있지만, 비동기 Sonnet 파이프라인 폐기 이후로는 새 카드에 사용되지 않는 레거시 값입니다.
우선순위 뱃지
상태와 별개로 각 카드에는 critical / high / medium / low 우선순위가 붙습니다. critical은 회귀나 보안 영향, low는 마이크로 최적화입니다.
Plan.md와 Copy-for-AI
Plan.md는 단순한 작업 지시서가 아니라, 그 자체가 Claude·Codex·Cursor 안에서 즉시 실행 가능한 명령입니다. 헤더에 메타데이터(타겟 URL, 브랜드 킷 ID, 아티팩트 유형 등)가 있고, 본문은 정해진 템플릿에 카드 컨텍스트(제품·페르소나·금지어 등)를 끼워 넣어 만들어진 단계별 설명입니다.
실행 방법 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 호환을 위해 그대로 유지됩니다.)
Write Target — 라이브 / 섀도우 / 로컬
PDP 가이드를 생성할 때 결과물을 어디에 저장할지 선택합니다. 이 값은 카드의 write_target으로 기록됩니다.
| Write Target | 동작 |
|---|---|
| live | Shopify·Cafe24 스토어에 직접 반영 — 감사 로그 + 되돌리기 가능 |
| shadow | 스토어에는 적용하지 않고 AEKO에 결과물만 저장 — 미리보기 + 수동 적용 |
| local | 클립보드 / 로컬 파일로만 출력 — Claude가 실행해 결과만 받고 끝 |
처음에는 shadow를 권장
live는 즉시 라이브 사이트를 바꿉니다. 처음 한두 개 카드는 shadow로 실행해 결과물을 검토한 뒤, 톤과 형식이 만족스러우면 live로 전환하세요. 모든 live 쓰기는 자동 감사 로그에 남고 되돌릴 수 있습니다.
티어 게이팅
모든 개선 가이드 아티팩트는 유료 플랜 전체에서 동작합니다. 백엔드의 ARTIFACT_TIER_REQUIRED 맵이 단일 진실 공급원이며, 모든 항목이 starter 이상으로 게이팅됩니다.
| 기능 | 최소 티어 |
|---|---|
PDP HTML 리라이트 (pdp_html) | Starter |
제품 JSON-LD 생성 (json_ld) | Starter |
| 기술 점검 가이드 (llms.txt, robots.txt, technical_bundle) | Starter |
스토어 라이브 쓰기 (write_target=live) | Starter |
콘텐츠 변형 — 자체 블로그용 (own_store_markdown) | Starter |
콘텐츠 변형 — 외부 매체용 (external_media_markdown) | Starter |
플랜 차이는 추적 프롬프트·도메인·시장 한도에서 나타납니다 — 구독 요금제 가이드를 참고하세요.
스토어 쓰기 되돌리기
live로 쓰여진 모든 변경은 Settings → 스토어 연동 → Store Write Audit에 자동 기록됩니다. 행 단위로 펼치면 변경 전 값과 변경 후 값을 비교할 수 있고, "되돌리기" 버튼으로 한 번에 이전 상태로 복원합니다.
감사 로그에 남는 정보
- 실행자 (사용자 또는 MCP) + 타임스탬프
- 플랫폼 (Shopify, Cafe24) + 외부 제품 ID
- 오퍼레이션 (description, json_ld, tags, meta 등)
- 이전 값과 새 값의 전체 JSONB 스냅샷
- 상태 (성공/실패) + 되돌리기 참조 ID
주의
되돌리기는 AEKO가 직접 쓴 필드만 복원합니다. 그 사이에 스토어에서 직접 수정한 변경은 보존되지 않으니, 되돌리기 전에 라이브 페이지를 한 번 확인하세요.
End-to-End 예시
PDP 1건을 끝까지 실행하기
- 1.
/dashboard/improve/pdp에서 카탈로그 검색 → 인용성 낮은 제품 선택 - 2. "개선 가이드 만들기" → write_target=
shadow로 설정 - 3. 카드는 즉시
ready상태로 생성됨 - 4. "복사" → Claude Desktop에 Cmd+V → Enter
- 5. aeko-mcp이 Plan을 실행해 리라이트된 HTML과 JSON-LD를 결과 뷰에 저장
- 6. 결과가 만족스러우면 같은 카드를 write_target=
live로 다시 생성하거나, 결과 뷰의 "라이브 적용" 버튼 클릭 - 7. Measure → Readiness에서 며칠 후
content_change_detected→citability_improved이벤트 확인
MCP 없이도 쓸 수 있나요?
네. 카드 결과 뷰에서 생성된 HTML·JSON-LD를 직접 복사해 사이트에 수동으로 붙여넣어도 됩니다. MCP는 자동화를 위한 옵션이지 필수가 아닙니다. MCP 설치 방법은 에이전트 설정 가이드를 참고하세요.