Claude Ads
- 추천0
- GitHub 별11K
- 마케팅라이선스MIT
12개 광고 플랫폼의 계정 데이터를 읽고 잘 되는 것·고장 난 것·먼저 고칠 것을 알려 주는 광고 감사 스킬(읽기 전용, MIT)
요약
12개 광고 플랫폼의 계정 데이터를 읽고 잘 되는 것·고장 난 것·먼저 고칠 것을 알려 주는 광고 감사 스킬(읽기 전용, MIT)
설명
Claude Ads
Claude Ads는 Claude Code용 무료 오픈소스 스킬입니다. 광고 계정 데이터를 주면 12개 광고 플랫폼에 걸쳐 무엇이 잘 되고 있는지, 무엇이 고장 났는지, 무엇부터 고쳐야 하는지 알려 줍니다.
에이전시, 컨설턴트, 사내 마케팅팀을 위해 만들었습니다. 데이터를 읽고 결과를 보고할 뿐, 스스로 계정을 바꾸지는 않습니다.
📌 Claude Ads는 두 곳에서 받을 수 있습니다. 공개 릴리스는
AgriciDaniel/claude-ads(MIT 라이선스, 회원 가입 불필요)이고, 커뮤니티 미러는AI-Marketing-Hub/claude-ads입니다. AI Marketing Hub Pro 회원은 미러에서 먼저 써 보고 직접 협업할 수 있습니다.
빠른 시작
- 설치합니다(아래 「설치」 참고):
/plugin marketplace add agricidaniel/claude-ads를 실행한 뒤/plugin install claude-ads@ai-marketing-hub-claude-ads를 실행합니다. /ads setup을 실행하고 몇 가지 질문에 답합니다: 사업 모델, 목표, 주요 전환, 월 광고비, 운영 중인 플랫폼, 변경을 승인하는 사람. API 키나 토큰은 절대 붙여 넣지 마세요.- 근거 자료를 가져옵니다: 계정 내보내기 파일(CSV 또는 JSON), 스크린샷, 또는 기간 · 통화 · 시간대를 적은 요약 붙여 넣기.
/ads audit google(또는/ads audit all)을 실행합니다. 통과한 것, 실패한 것, 빠진 것을 밝힌 보고서를 받습니다./ads report로 지난 실행 결과를 다시 보고,/ads next로 가장 중요한 걸림돌을 확인합니다.
할 수 있는 일
| 하고 싶은 일 | 실행 | 받는 것 |
|---|---|---|
| 무엇이 잘못됐는지 찾기 | /ads audit | 통과 · 실패 · 미확인 항목과 각각의 근거를 담은 보고서 |
| 어디에 쓸지 정하기 | /ads plan | 채널, 예산, 측정, 경쟁사 계획 |
| 광고 만들기 | /ads create | 문구, 이미지, 영상, 제품 사진 브리프와 결과물 |
| 계속 지켜보기 | /ads monitor | 집행 속도, 노출, 추적, 광고 피로도, 정책 점검 |
| 성과 개선하기 | /ads optimize --draft | 초안 형태로 쓴 개선 제안 |
| 아이디어 시험하기 | /ads experiment | 테스트 설계, 또는 끝난 테스트의 결과 해석 |
플랫폼
플랫폼마다 전용 스킬, 감사 작업자, 관리 항목 참고 자료, 기능 선언이 따로 있습니다. 실제로 읽거나 바꿀 수 있는 범위는 기능 매니페스트가 공식 기록입니다.
명령
독립 설치는 /ads를 씁니다. Claude Code 플러그인은 이름공간이 붙어 /claude-ads:ads를 씁니다. 둘 다 같은 ads/SKILL.md 규약을 불러옵니다.
| 명령 | 하는 일 |
|---|---|
/ads setup | 고객, 계정, 목표, 개인정보, 안전 장치 프로필 저장 |
/ads audit [all|platform|scope] | 근거에 기반한 전체 또는 범위 한정 감사 실행 |
/ads plan | 채널, 캠페인, 예산, 경쟁사, 측정 계획 수립 |
/ads create | 문구, 이미지, 영상, 제품 사진 결과물 제작 |
/ads launch --draft | 계정을 건드리지 않고 캠페인 변경 계획 초안 작성 |
/ads monitor | 집행 속도, 노출, 추적, 피로도, 정책, 성과 점검 |
/ads optimize --draft | 근거 있는 개선안 초안 작성 |
/ads experiment | 통제된 테스트 설계 또는 결과 해석 |
/ads report | 저장된 실행 결과를 Markdown, HTML, PDF로 출력 |
/ads research refresh | 플랫폼, 정책, API, 벤치마크 근거 새로 고침 |
/ads validate | 규약, 실행 결과, 기능, 릴리스 준비 상태 점검 |
/ads status, /ads next | 현재 상태와 가장 중요한 걸림돌 표시 |
/ads google, /ads meta, /ads amazon, /ads reddit 같은 플랫폼 바로가기는 그 플랫폼의 감사로 곧장 들어갑니다.
믿을 수 있게 만들었습니다
모든 점검은 pass, fail, unknown, not_applicable 넷 중 하나로 끝납니다. 「알 수 없음」은 정식 답입니다. 데이터가 없었다는 뜻이고, 추측으로 채우지 않습니다.
Claude Ads Cockpit (선택)
Cockpit은 따로 설치하는 선택 동반 도구입니다(버전 0.1.0, 플러그인 ID ads-cockpit). /ads-cockpit을 실행하면 끝난 감사를 살펴볼 수 있는 로컬 작업대가 열립니다. 상태, 근거, 빠진 입력, 이전 실행과의 비교, 보고서 영수증을 볼 수 있습니다. 합성 데이터로 만든 데모가 들어 있어 계정 없이도 써 볼 수 있습니다.
작업 수 집계는 건강 점수와 분리되어 있고, 점수 매니페스트의 모든 점수 프로필은 꺼져 있습니다. Cockpit 안내서와 호환성 및 인수 한계를 참고하세요.
설치
Claude Code가 기준 실행 환경입니다. Codex, Gemini, Cursor, Windsurf, Goose와 Agent Skills를 지원하는 호스트에서는 그 런타임이 지원하는 범위에서 같은 스킬 파일을 쓸 수 있습니다.
호스트의 기본 플러그인 방식이나, SHA-256 체크섬을 검증한 태그 릴리스 압축 파일을 쓰세요. 원격 설치 스크립트를 셸로 바로 파이프하지 마세요.
Claude Code의 기본 플러그인 방식은 다음과 같습니다.
/plugin marketplace add agricidaniel/claude-ads
/plugin install claude-ads@ai-marketing-hub-claude-ads
v2.0.0 이전에 이 마켓플레이스를 추가했다면 Claude Code가 아직 예전 로컬 별칭 agricidaniel-claude-ads를 들고 있습니다. 그 별칭을 지운 뒤 다시 추가하고 설치하세요.
/plugin marketplace remove agricidaniel-claude-ads
/plugin marketplace add agricidaniel/claude-ads
/plugin install claude-ads@ai-marketing-hub-claude-ads
관리형 의존성은 CPython 3.11 또는 3.12가 필요합니다. Linux x86_64는 glibc 2.28 이상이 필요하고 musl은 지원하지 않습니다. macOS 11 x86_64/arm64와 Windows amd64는 선언된 wheel 대상이지만 네이티브 CI 검증이 더 필요합니다. CI는 AlmaLinux 8(glibc 2.28) 컨테이너에서 지원하는 두 인터프리터로 Linux 최소 요건을 확인합니다. 이 확인은 Python wheel과 관리형 CLI 수명 주기를 대상으로 하며, 브라우저 페이로드와 PDF 시스템 라이브러리는 호스트에서 따로 검증해야 합니다.
또는 공개 저장소의 로컬 복제본에서 설치합니다.
git clone https://github.com/AgriciDaniel/claude-ads.git
cd claude-ads
bash install.sh --source=local
다른 독립 호스트를 명시적으로 고르려면 다음과 같이 합니다.
bash install.sh --target=codex --source=local
bash install.sh --target=gemini --source=local --no-deps
⚠️ 실험적: 검증된 곳은 Claude Code뿐입니다. Codex, Gemini, Cursor, Windsurf, Goose 대상은 각 호스트가 기대하는 디렉터리에 같은 스킬 결과물을 설치하지만, 호스트의 런타임 규칙이 다를 수 있습니다. 결과를 호스트에서 확인하고, 자동 감지된 경로가 틀리면
--skill-dir과--agent-dir로 설치 위치를 지정하세요. 설치 프로그램은claude와codex대상에서만 관리형 Python 환경을 만듭니다.
--source=git(체크아웃 밖에서 설치 프로그램을 실행할 때의 기본값)은 기본 브랜치 HEAD를 복제하는데, 이는 고정되지 않았고 검증된 릴리스도 아닙니다. 검토한 체크아웃에서 --source=local을 쓰거나 릴리스 압축 파일을 쓰는 편이 좋습니다.
git 설치를 고정하려면 선택 옵션 --ref(PowerShell은 -Ref)에 태그, 브랜치, 커밋을 붙입니다. --source=git에서만 쓸 수 있습니다. 설치 프로그램은 값을 엄격히 검사하고, 분리된 HEAD로 체크아웃하며, 확인된 전체 커밋 SHA를 출력하고, ref를 찾지 못하면 아무것도 설치하기 전에 실패합니다.
bash install.sh --source=git --ref=v2.1.0
git ref는 체크섬을 검증한 릴리스가 아니며, 여기 있는 어떤 것도 서명되어 있지 않습니다. 아래 SHA256SUMS 방법으로 확인한 릴리스 zip이 검증된 경로입니다.
PowerShell도 같은 관리형 소유 모델을 씁니다.
git clone https://github.com/AgriciDaniel/claude-ads.git
Set-Location claude-ads
.\install.ps1 -Source local
릴리스 압축 파일은 쓰기 전에 검증하세요. GitHub 릴리스마다 zip, release-manifest.json, sbom.cdx.json, SHA256SUMS 파일이 올라옵니다. 릴리스는 서명이 아니라 체크섬만 제공하므로, 체크섬은 파일이 릴리스에 게시된 것과 같다는 것만 확인할 뿐 출처를 독립적으로 증명하지는 않습니다. 네 파일을 모두 빈 디렉터리 하나에 내려받은 뒤 다음을 실행합니다.
sha256sum -c SHA256SUMS # macOS: shasum -a 256 -c SHA256SUMS
모든 줄이 OK로 나와야 압축을 풀고 풀린 폴더에서 bash install.sh --source=local을 실행할 수 있습니다.
관리형 의존성은 선언된 Linux, macOS, Windows wheel 조합에서 CPython 3.11과 3.12를 지원합니다. 지원하지 않는 인터프리터는 대상 위치가 바뀌기 전에 실패합니다. 스킬만 설치하려면 --no-deps 또는 -NoDeps를 쓰세요.
브라우저 캡처에는 운영자가 설치한 Playwright 브라우저 페이로드가 필요합니다. PDF 렌더링에는 호스트의 WeasyPrint와 Pango 시스템 라이브러리가 필요합니다. 이 내용은 외부 런타임 의존성 매니페스트에 문서화되어 있습니다.
설치 관리 목록에 있는 파일만 제거합니다.
bash uninstall.sh --target=claude
PowerShell에서는 uninstall.ps1이 같은 역할을 합니다.
Bash와 PowerShell 스킬 설치 프로그램은 Cockpit을 켜거나 불러오지 않습니다. Cockpit의 선택 플러그인은 별도의 마켓플레이스 항목과 선별된 압축 파일이 있고, 신뢰할 수 있는 코어와 Python 실행 파일을 명시적으로 지정해야 합니다. 메인 스킬만 설치하면 기존 사용 경험은 그대로 유지됩니다.
프로젝트 상태
❗ 상태: 개발 후보. RELEASE_REQUIREMENTS.md의 모든 관문이 새로운 검증 환경에서 통과하기 전에는 Claude Ads를 릴리스 준비 상태로 보지 않습니다.
- 12개 계정 건강 점수 프로필이 모두 꺼져 있어 건강 점수는 만들어지지 않습니다. 감사는 점수 대신 발견 사항, 미확인 항목, 근거 범위를 보고합니다.
- Cockpit 동반 도구는 선택 사항이며 아직 네이티브로 인수되지 않았습니다. 호환성 및 인수 한계를 참고하세요.
- 전체 변경 관문을 통과하지 못하면 계정 변경은 초안으로만 남습니다.
엔지니어와 기여자를 위해
어떻게 만들었고, 점수는 어떻게 매기고, 안전 관문은 무엇이며, 테스트는 어떻게 돌리는지
아키텍처
한 명의 지휘자가 범위, 정책, 집계, 최종 결과물을 맡습니다. 작업자들은 제한된 조각을 분석해 스키마에 맞는 발견 사항을 돌려줍니다. 필수 작업자가 실패하면 그 실행은 부분 결과가 되며, 완전한 감사처럼 조용히 보여 주지 않습니다.
에이전트 정의에는 모델을 고정하지 않습니다. 모델은 호스트나 호출 쪽이 고르며, 더 우선하는 선택이 없으면 Claude Code는 메인 대화의 모델을 이어받습니다. 공식 서브에이전트 모델 문서를 참고하세요.
표준 결과는 버전이 매겨진 JSON입니다. Markdown, HTML, PDF는 검증된 같은 실행 묶음을 다르게 그린 것입니다.
점수와 근거
점검 항목은 pass, fail, unknown, not_applicable을 씁니다.
- 건강, 근거 범위, 규제 노출, 기회는 서로 분리해 둡니다.
- 알 수 없는 항목은 알려진 건강 상태를 바꾸지 않고 근거 범위만 낮춥니다.
- 근거 범위가 80% 이상이면 등급을 매기고, 60~79%는 잠정, 60% 미만은 근거 부족입니다.
- 선택, 베타, 프리미엄, 사용 불가, 자격 미달 기능은 점수에 넣지 않습니다.
- 꺼져 있거나 승인되지 않은 플랫폼 프로필은 건강 점수를 만들지 않습니다.
- 실패한 플랫폼은 포트폴리오 점수에서 빠지고 그 실행은 부분 결과가 됩니다.
점수 체계 참고 자료와 실제 구현인 claude_ads_core/scoring.py를 참고하세요.
계정 안전
모든 어댑터는 기본이 읽기 전용입니다. 변경을 적용하려면 다음이 모두 필요합니다.
- 그 작업에 대해 테스트를 마치고 켜 둔 기능.
- 명시적인 계정 · 객체 ID.
- 영향 범위가 담긴, 사람이 읽을 수 있는 변경 전후 비교.
- 계정에서 정한 상한 안에서의 소유자 승인.
- 멱등성 키, 감사 기록 위치, 롤백, 검증 기간.
- 원격 상태가 변경 전제 조건과 아직 같은지 확인.
상한이 없으면 쓰기를 하지 않습니다. v2는 영구 삭제를 지원하지 않습니다. 자격 증명은 환경 변수, OS 키체인, 승인된 비밀 관리자에 두세요. 저장소, 프로필, 보고서, 로그에는 절대 넣지 않습니다.
근거와 릴리스 통제
공개해도 안전한 control-plane/에는 제품 경계, 날짜가 있는 출처, 주장, 기능, 안전 규칙, 개인정보 규칙, 생태계 결정, 릴리스 요건이 기록되어 있습니다.
- 출처가 없으면 현재 플랫폼에 대한 주장을 하지 않습니다.
- 구현, 픽스처, 테스트가 없으면 기능 주장을 하지 않습니다.
- 승인과 롤백이 없으면 계정을 바꾸지 않습니다.
- 독립적인 검증이 없으면 릴리스하지 않습니다.
MIT 공개 배포본과 비공개 개발 · 커뮤니티 저장소는 게시 경계가 서로 다릅니다. 로컬 검증은 새 릴리스, 공개 범위 변경, 비공개 검토 근거의 게시를 승인하지 않습니다.
런타임 명령은 소스 체크아웃 옆이나 선별된 독립 설치본에서 정책을 찾습니다. 다른 정책 위치를 쓰려면 --policy-root ROOT를 쓰세요. status와 next는 호환용 별칭으로 --root ROOT를 유지합니다. 명령은 관련 없는 작업 디렉터리에서 정책을 고르지 않습니다. 저장소 감사와 릴리스 도우미에는 소스 체크아웃이 필요합니다.
공개 점수 계산은 표준 레지스트리를 씁니다. 예전 방식의 항목과 범주 가중치 입력은 승인된 정책과 정확히 일치할 때만 받습니다. 보고서 상태와 렌더링은 조작된 건강 점수나 호환되지 않는 과거 묶음을 거부하니, 그런 묶음은 현재 레지스트리로 다시 만드세요. 12개 운영용 건강 프로필은 심각도와 가중치 정책이 승인될 때까지 모두 꺼져 있어, 건강 점수는 null이고 승인된 근거 범위는 0입니다.
개발
가상 환경을 만들고 전체 테스트를 돌립니다.
python3.12 -m venv .venv
.venv/bin/python -m pip install --no-deps -e .
.venv/bin/python -m pip install --require-hashes --only-binary=:all: -r requirements.lock
.venv/bin/python -m pip install --require-hashes --only-binary=:all: -r requirements-dev.lock
.venv/bin/python -m pip install --require-hashes --only-binary=:all: -r .github/requirements-schema-tests.lock
.venv/bin/python -m pip check
.venv/bin/python -m pytest -q
유용한 부분 점검:
python -m claude_ads_core --version
python -m claude_ads_core validate finding path/to/finding.json
bash -n install.sh uninstall.sh
참고 문서
- Cockpit 구현 규약: 선택 동반 도구와의 통합 경계.
- 요구 사항 색인: 추적 장부가 연결하는 고정 요구 사항 ID.
- 제어 스키마 이전, v1에서 v2로: 제어 스키마에서 바뀐 점.
저장소 구조
ads/ 메인 스킬, 인터페이스 메타데이터, 공유 참고 자료
skills/ 플랫폼 · 수명 주기 스킬
agents/ 플랫폼, 교차 플랫폼, 조사, 검증 작업자
claude_ads_core/ 타입 규약, 어댑터, 검증, 점수
control-plane/ 근거, 기능, 안전, 성숙도, 릴리스 상태
scripts/ 브라우저, 창작, 보고, 릴리스 도우미
evals/ 라우팅과 동작 평가 사례
tests/ 결정론, 보안, 설치, 어댑터 테스트
기여하기
문제를 찾았거나 아이디어가 있나요? CONTRIBUTING.md를 보세요.
문제를 제보하고 수정을 제안해 준 모든 분께 감사드립니다: @aleps001, @bq9kpv2h98-max, @haruntekin89, @reikjarloekl, @osilova, @Nath24591, @sistemasond-ux, @principisimone-sys, @HarKro753, @plcosta, @ulises2k, @kutzki, @SamaEducationalCo, @Bortlesboat, @gabbyran2026-gif, @AbundantASG, @hendrixfreire, @josefresco, @dead-simba, @c6zks4gssn-droid, @kershrita, @popey, @xiaolai, @seojcarlos, @botbikamordehai2-sketch. 각자 어떤 기여를 했는지는 CONTRIBUTING.md에 있습니다.
개인정보
고객 데이터, 비공개 원본 조사 자료, 수집한 프롬프트, 자격 증명, 계정 내보내기 파일, 에이전트 대화 기록은 Git 기록, 보고서, 릴리스 압축 파일에 절대 넣지 않습니다. 자격 증명은 환경 변수, OS 키체인, 승인된 비밀 관리자에 두세요.
라이선스
Claude Ads의 원본 코드와 문서는 MIT 라이선스로 제공됩니다. 서드파티 API, 상표, 문서, 인용한 자료는 각자의 약관을 따릅니다. 외부 작업을 가져오기 전에 출처 장부와 서드파티 고지를 확인하세요.
평점
- 5점
- 0
- 4점
- 0
- 3점
- 0
- 2점
- 0
- 1점
- 0