Claude Ads

에이전시, 컨설턴트 및 사내 퍼포먼스 팀을 위한 클라우드 기반의 포터블(portable) 유료 미디어 운영 솔루션입니다.

Claude Ads는 승인된 내보내기(exports) 또는 계정 읽기(account reads)를 출처가 명시된 감사(audits), 계획, 크리에이티브 워크플로우, 실험, 모니터링 및 보고서로 변환합니다. 기본적으로 읽기 전용(read-only)입니다. 실시간 변경 사항은 정확한 플랫폼과 작업이 승인, 아이덴티티(idempotency), 검증(verification), 감사(audit), 롤백 게이트를 통과할 때까지 비활성화된 상태로 유지됩니다.

[!NOTE]
Claude Ads는 두 곳에서 제공됩니다: AgriciDaniel/claude-ads의 공개 릴리스 (MIT, 멤버십 불필요)와 AI Marketing Hub Pro 회원들이 조기 액세스 및 직접 협업을 할 수 있는 커뮤니티 미러인 AI-Marketing-Hub/claude-ads입니다.

기능 (What it does)

• 날짜가 명시된 증거와 명확한 신뢰도를 바탕으로 유료 미디어 계정을 감사합니다.
• 캠페인, 채널, 예산, 측정 및 실험을 계획합니다.
• 카피, 이미지, 비디오, 제품 사진 브리프 및 에셋을 생성합니다.
• 페이싱(pacing), 전달량(delivery), 추적(tracking), 피로도(fatigue), 정책(policy) 및 성과를 모니터링합니다.
• 버전 관리되는 JSON을 생성한 후 Markdown, HTML 및 선택적으로 PDF로 렌더링합니다.
• 기본적으로 적용하지 않으면서 안전한 계정 변경 사항을 초안 작성합니다.
• 누락된 데이터, 오래된 출처(stale sources), 모순점, 부분적인 실패를 보고합니다.

플랫폼 (Platforms)

각 플랫폼은 특화된 스킬(skill), 감사 작업자(audit worker), 제어 참조(control reference), 역량 선언(capability declaration) 및 테스트 가능한 라우팅 영역을 가지고 있습니다. 역량 매니페스트는 실시간 읽기 및 쓰기에 대한 권위 있는 기록입니다.

명령어 (Commands)

단독 설치(Standalone installs)는 /ads를 사용합니다. Claude Code 플러그인은 네임스페이스가 지정되어 /claude-ads:ads를 사용합니다. 둘 다 동일한 ads/SKILL.md 계약을 로드합니다.

데모 (Demo)

이 GIF는 원래의 명령어 발견(command-discovery) 경험을 보여줍니다. 위에 있는 v2 명령어 테이블과 플랫폼 테이블이 현재적이며 권위 있습니다.

설치 (Installation)

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

또는 공개 저장소의 로컬 클론에서 설치하십시오:

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

PowerShell은 동일한 관리 소유 모델을 사용합니다:

git clone https://github.com/AgriciDaniel/claude-ads.git
Set-Location claude-ads
.\install.ps1 -Source local

관리되는 의존성은 선언된 Linux, macOS 및 Windows 휠 매트릭스에서 CPython 3.11 및 3.12를 지원합니다. 지원되지 않는 인터프리터는 목적지 변경 전에 실패합니다. 스킬 전용 설치를 위해서는 --no-deps 또는 -NoDeps를 사용하십시오.

브라우저 캡처에는 운영자가 설치한 Playwright 브라우저 페이로드가 필요합니다. PDF 렌더링에는 호스트의 WeasyPrint 및 Pango 시스템 라이브러리가 필요합니다. 이들은 외부 런타임 의존성 매니페스트에 문서화되어 있습니다.

매니페스트 소유 파일만 제거하십시오:

bash uninstall.sh --target=claude

PowerShell의 등가물은 uninstall.ps1입니다.

아키텍처

하나의 컨덕터(conductor)가 범위(scope), 정책(policy), 집계(aggregation), 그리고 최종 아티팩트(artifacts)를 소유합니다. 워커(workers)는 경계가 지정된 슬라이스(bounded slices)를 분석하고 스키마 유효성 검사를 통과한 발견 사항을 반환합니다. 필수 워커의 실패는 실행을 부분적으로 만듭니다. 이는 결코 완전한 감사로 조용히 제시되지 않습니다.

표준 결과물은 버전이 지정된 JSON입니다. 마크다운(Markdown), HTML, PDF는 동일하게 검증된 실행 번들(validated run bundle)의 렌더링입니다.

점수 산정 및 증거 (Scoring and evidence)

컨트롤(Controls)은 pass, fail, unknown, 또는 not_applicable을 사용합니다.

• 건강 상태(Health), 증거 커버리지(evidence coverage), 규제 노출(regulatory exposure), 그리고 기회는 분리되어 유지됩니다.
• 알 수 없는 컨트롤(Unknown controls)은 알려진 건강 상태를 변경하지 않으면서 증거 커버리지를 감소시킵니다.
• 80% 이상의 커버리지는 '등급(graded)'으로, 60~79%는 '잠정적(provisional)'으로, 60% 미만은 '불충분한 증거(insufficient evidence)'로 분류됩니다.
• 선택 사항(Optional), 베타(beta), 프리미엄(premium), 사용 불가(unavailable), 그리고 부적격(ineligible) 기능은 점수 산정에서 제외됩니다.
• 비활성화되거나 승인되지 않은 플랫폼 프로필은 건강 점수를 생성하지 않습니다.
• 실패한 플랫폼은 포트폴리오 점수 산정에서 제외되며 실행을 부분적으로 만듭니다.

점수 산정 참고 자료(scoring reference)와 claude_ads_core/scoring.py의 프로덕션 구현을 참조하십시오.

계정 안전성 (Account safety)

모든 어댑터(adapters)는 기본적으로 읽기 전용입니다. 변경 사항을 적용하려면 다음이 필요합니다:

1. 정확한 작업을 위한 테스트되고 활성화된 기능(capability).
2. 명시적인 계정 및 객체 ID.
3. 영향 범위(blast radius)가 포함된 사람이 읽을 수 있는 이전/이후 차이점(before and after diff).
4. 계정 정의 한계 내의 소유자 승인(Owner approval).
5. 비멱등성 키(idempotency key), 감사 목적지(audit destination), 롤백(rollback), 그리고 검증 기간(verification window).
6. 원격 상태가 여전히 변경 전 조건(mutation precondition)과 일치하는지에 대한 검증.

한계가 누락되면 쓰기 작업이 불가능합니다. 영구 삭제는 v2에서 지원하지 않습니다. 자격 증명(Credentials)은 환경 변수, OS 키체인 또는 승인된 비밀 관리자(secret manager)에 보관되어야 합니다. 절대로 저장소(repository), 프로필, 보고서 또는 로그에 포함되어서는 안 됩니다.

증거 및 릴리스 제어

control-plane/ 레코드는 제품 경계, 날짜가 지정된 출처, 주장(claims), 기능(capabilities), 안전 규칙, 개인 정보 보호 규칙, 에코시스템 결정 및 릴리스 요구 사항을 기록합니다.

• 출처가 없다는 것은 현재 플랫폼 주장이 없음을 의미합니다.
• 구현, 고정값(fixture) 및 테스트가 없다는 것은 기능 주장이 없음을 의미합니다.
• 승인 및 롤백이 없다는 것은 계정 변경이 없음을 의미합니다.
• 독립적인 검증이 없다는 것은 릴리스가 없음을 의미합니다.

릴리스 요구 사항과 게시 정책을 참조하십시오.

개발

가상 환경을 생성하고 전체 스위트를 실행합니다:

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
...

유용한 집중 검사:

python -m claude_ads_core --version
python -m claude_ads_core validate finding path/to/finding.json
bash -n install.sh uninstall.sh

리포지토리 맵

ads/                  주요 기능(main skill), 인터페이스 메타데이터 및 공유 참조
skills/               플랫폼 및 라이프사이클 기능
agents/               플랫폼, 크로스-플랫폼, 연구 및 검증기 워커
...

기여자 및 감사의 말씀

Claude Ads는 커뮤니티의 버그 보고서, 기능 요청 및 제안된 수정 사항으로부터 혜택을 받았습니다. v2.0.2에 정보를 제공한 다음 기여자들에게 감사드립니다. 일부 제안은 독립적으로 구현되었거나 대체되었습니다. 이 크레딧은 제출된 모든 패치가 병합되었다는 것을 의미하지는 않지만, 기여를 인정합니다.

문제를 보고하거나 변경을 제안하려면 CONTRIBUTING.md를 참조하십시오.

개인 정보 보호

클라이언트 데이터, 원시 개인 리서치, 캡처된 프롬프트, 자격 증명(credentials), 계정 내보내기(account exports), 에이전트 기록(agent transcripts)은 절대 Git 히스토리, 보고서 또는 릴리스 아카이브에 포함되어서는 안 됩니다. 자격 증명은 환경 변수, OS 키체인 또는 승인된 비밀 관리자(secret manager)에 보관하십시오.

라이선스

원래 Claude Ads 코드와 문서는 MIT License 하에서 이용 가능합니다. 타사 API, 상표, 문서 및 인용된 아티팩트는 자체 약관의 적용을 받습니다. 외부 작업을 가져오기 전에 소스 원장(source ledger)과 타사 고지 사항(third-party notices)를 검토하십시오.