웹사이트 카피 리뷰

웹사이트 카피 리뷰은(는) 무엇을 하나요?

웹사이트 코드베이스를 비기술적 리뷰어가 페이지별로 읽고 마크업할 수 있는 문서로 변환합니다. 모든 문자열에는 주소(Ref 코드)가 유지되어 리뷰어의 수정 사항을 기계적으로 원본에 적용할 수 있습니다.

이런 방식으로 만든 이유

웹사이트 카피는 산문이 아닙니다. 마크업 내 고정된 레이아웃 슬롯에 들어 있는 수백 개의 짧은 문자열입니다. 따라서:

• 산문 덤프에 변경 추적을 적용하면 돌아오는 것은 마크업에 다시 배치할 수 없는 삽입의 연속입니다. 그래서 문자열마다 하나의 행에 Ref 코드를 부여합니다.
• 4단어 카드 제목을 12단어로 바꾼 리뷰어는 레이아웃이 깨지는 것을 Word에서는 확인할 수 없습니다. 그래서 제약이 있는 행에는 문자 수와 평이한 길이 안내를 제공합니다.
• 리뷰어는 코드를 볼 수 없습니다. 그래서 모든 행이 무엇인지("버튼 레이블", "대체 텍스트") 평이한 용어로 설명하고, 모든 페이지 섹션은 사이트 내 위치를 명시합니다.

문서는 톤과 내러티브를 평가할 수 있도록 페이지별로 위에서 아래로 읽히면서도 각 문자열이 개별적으로 주소 지정 가능해야 합니다.

번들 파일

scripts/merge_and_verify.py, scripts/build_review_docx.py, references/extraction-brief.md 그리고 assets/pages.example.json이 이 파일과 함께 있습니다. 만약 이 파일들이 누락되었다면(스킬이 SKILL.md로만 설치된 경우), ~/my-skills/website-copy-review/ 또는 brianitsup/website-copy-review 저장소에서 찾으십시오. 둘 다 접근할 수 없다면, 문서 레이아웃을 임의로 구성하지 말고 사용자에게 알리십시오. 레이아웃은 실행 간에 달라져서는 안 되기 때문입니다.

기본 규칙

• 읽기 전용. 저장소를 절대 수정하지 마십시오. 모든 출력은 사용자가 저장소 내에 요청하지 않는 한 스크래치패드로 보냅니다.
• python-docx를 전역이 아닌 스크래치패드의 virtualenv에 설치합니다: python3 -m venv <scratch>/venv && <scratch>/venv/bin/pip install python-docx
• 정직하게 보고합니다. 파일을 파싱할 수 없거나 검사를 실행할 수 없는 경우, 조용히 범위를 좁히지 말고 그렇게 알리십시오.
• 저장소에 AGENTS.md, CLAUDE.md, PROJECT_WORKFLOW.md 또는 CONTRIBUTING.md에 이슈 우선(또는 유사) 워크플로 규칙이 있다면, 사용자에게 반환된 수정 사항과 결함 사항을 구현하기 전에 이슈가 필요하다는 것을 알리십시오. 요청 없이 이슈를 열지 마십시오.

규모를 예상하십시오: 중간 규모 브로셔 사이트는 약 15-20페이지에 400-600개 항목, 50-60페이지 분량의 문서입니다. 이는 정상이며, 페이지별 표가 탐색을 용이하게 합니다.

1단계 — 범위 설정 (한 번에 기본값과 함께 질문)

이 항목들을 함께 질문하고(AskUserQuestion 사용 가능), 기본값을 권장합니다:

1. 어떤 카피? 템플릿/컴포넌트의 하드코딩된 카피만 (기본값 — 편집자 콘텐츠는 코드 변경 없이 CMS에서 수정 가능), 또는 CMS에서 작성된 게시물/페이지도 포함?
2. 리뷰어는 어떻게 변경 사항을 표시할까요? 빈 "수정 제안" 컬럼 (기본값 — 명확하고 기계적으로 적용 가능), 또는 Word 주석/변경 추적(자연스럽지만 적용이 어려움).
3. 어떤 콘텐츠 상태? 작업 트리, 또는 라이브/프로덕션? 로컬 데이터베이스나 콘텐츠 스냅샷이 실제 게시된 것과 차이가 있을 수 있음을 표시합니다.

사용자가 자리를 비운 경우 기본값을 선택하고 보고서 상단에 그렇게 알립니다. 답변은 표지 페이지(pages.json의 meta.scope)에 들어갑니다.

2단계 — 카피 위치 파악

스택을 가정하지 마십시오. 저장소를 검사하고(package.json, 테마 매니페스트, 프레임워크 설정, 디렉토리 레이아웃) 다음 카피 소스를 나열합니다:

• 코드 내: .hbs, JSX/TSX, Vue, Svelte, Astro, Blade, ERB, Twig, PHP 테마, HTML, Markdown/MDX 콘텐츠 파일, i18n/로케일 JSON 또는 YAML.
• 코드 외부: CMS 데이터베이스/API(Ghost, WordPress, Sanity, Contentful, Strapi) 및 저장소에 없는 방문자 대상 사이트 설정 — 사이트 제목, 메타 설명, 내비게이션 레이블, 관리자에서 설정된 CTA/버튼 레이블. 이를 가져올 때는 원시 내보내기를 <scratch>/snapshots/에 저장하여 다른 소스와 같이 검증할 수 있게 합니다(4단계 참조).

다음과 같이 놓치기 쉬운 범주를 항상 포함하고, 리뷰어가 무엇인지 알 수 있도록 각각 레이블을 지정합니다: alt 텍스트(스크린 리더와 검색 엔진이 읽음 — 파트너/제품 이름이 정확해야 함), aria-label, 양식 플레이스홀더, 제출 레이블, 성공/오류/유효성 검사 메시지, 빈 상태, 404/오류 페이지, 저작권 표시 및 법적 바닥글.

각 페이지 템플릿을 실제 URL 경로에 매핑합니다(routes.yaml, 파일 기반 라우팅, 라우터 설정, CMS 페이지→템플릿 할당). 템플릿에 페이지나 경로가 없으면 해당 페이지의 노트에 명시적으로 기록합니다. 해당 카피는 접근할 수 없으며, 리뷰어가 시간을 낭비하기 전에 알아야 합니다.

그런 다음 <scratch>/pages.json을 assets/pages.example.json에서 작성합니다: 문서가 제시해야 하는 순서대로 페이지당 하나의 항목, key, title, url, source, 선택적 note, 그리고 meta 블록(프로젝트, 범위 답변, 제외 사항, 하드코딩된 카피가 없는 템플릿)을 포함합니다. 빌드 스크립트가 이것을 읽습니다 — 페이지 메타데이터는 절대 하드코딩되지 않습니다.

3단계 — 고정된 계약으로 병렬 추출

1. 먼저 전체 표면을 열거합니다: 모든 페이지 템플릿 그리고 해당 페이지가 포함하는 모든 부분/공유 컴포넌트(헤더, 푸터, 카드, 뉴스레터 양식, CTA). 부분 컴포넌트는 에이전트 간에 파일이 분할될 때 누락되는 요소입니다.
2. 겹치지 않는 그룹(대략 파일 3-6개 또는 약 1,500줄씩)으로 나누고 모든 파일을 명시적으로 할당합니다. 공유 부분 컴포넌트는 자체 페이지 항목(예: FOOTER, NAV)을 가지며 사이트 전체에 나타난다는 노트를 추가합니다. 모든 페이지 아래에 반복하지 않습니다.
3. 그룹당 하나의 서브 에이전트를 단일 턴에, 중간급 모델(예: Sonnet)로 생성합니다. 작업은 기계적이지만, 누락은 보이지 않고 치명적입니다. references/extraction-brief.md를 그대로 모든 프롬프트에 붙여넣고, 해당 에이전트의 파일 목록, 각 파일에 사용할 page_key, 저장소 루트, 출력 경로 <scratch>/extract/<group>.json을 추가합니다.
4. 반환되면, 열거된 모든 파일이 일부 출력에 나타나거나(또는 카피가 없다고 보고되었는지) 확인합니다. 누락된 것은 다시 할당합니다.

각 에이전트가 보고한 판단 호출을 수집합니다. 4단계와 최종 보고서에서 필요합니다.

4단계 — 독립적으로 병합 및 검증 (건너뛰지 마십시오)

에이전트 자체 점검은 검증이 아닙니다. 다음을 실행하십시오:

<venv>/bin/python scripts/merge_and_verify.py \
  --extract-dir <scratch>/extract --pages <scratch>/pages.json \
  --repo <repo-root> [--snapshot-dir <scratch>/snapshots] --out <scratch>/out

이 스크립트는 모든 추출물을 pages.json 순서로 병합하고, PAGEKEY-NN Ref를 할당하며, chars를 다시 계산하고, 모든 문자열을 해당 소스 파일에 대해 세 가지 점진적으로 느슨한 정규화(원시(공백 축소), 태그 제거, 공백 압축)로 다시 확인합니다. 각 정규화는 다른 것을 잡아내기 때문입니다(속성 텍스트는 원시를 통과하고 태그 제거에서 실패하는 것은 구조적으로 예상됨). 중복 Ref, 빈 텍스트, page_key가 pages.json에 없는 항목도 확인합니다. 출력: items.json, copy-review-manifest.csv, verification.md.

해결되지 않은 항목이 있는 한 종료 코드는 0이 아닙니다. 각 UNMATCHED 행에 대해 소스를 열어 확인합니다. 적법한 잔여물은 일반적으로 에이전트가 리터럴 하위 문자열이 아닌 렌더링된 텍스트를 기록한 조건부/루프 블록입니다. 기록한 대로 렌더링되는지 확인한 후, <scratch>/accepted.json에 {"REF": "reason"} 형식으로 나열하고 --accept <scratch>/accepted.json을 사용하여 다시 실행합니다. 진정한 오류는 추출 JSON(저장소 아님)에서 수정하고 다시 실행합니다. Ref는 병합 시 할당되므로, 데이터를 수정한 후 다시 실행한 다음 빌드합니다.

또한 완전성을 점검합니다: 가장 밀도가 높은 파일 두세 개를 골라 항목 수를 파일을 빠르게 읽어본 것과 비교합니다. 누락된 문자열은 자동화된 검사에 나타나지 않습니다.

5단계 — 문서 빌드

<venv>/bin/python scripts/build_review_docx.py \
  --pages <scratch>/pages.json --items <scratch>/out/items.json \
  --out <scratch>/out/<프로젝트명>-Website-Copy-Review.docx

스크립트가 레이아웃을 담당하므로 실행 간에 절대 변하지 않습니다: A4 가로, 1.4cm 여백; 표지(범위, 포함/제외 사항, 리뷰 방법, 길이에 민감한 행을 길이 근처에 유지, Ref 번호를 다시 매기거나 삭제하지 않음, 사실 — 연도, 직원 수, 수치, 파트너 이름, 직책 — 을 문구와 동일하게 주의 깊게 확인); 합계 및 빈 템플릿을 포함한 목차; 새 페이지에서 시작하는 페이지 섹션; 컬럼 Ref 2.2 / 요소 4.3 / 현재 카피 8.4 / 수정 제안 8.4 / 참고 사항 3.6 cm; 어두운 반복 헤더 행; 색상이 지정된 대문자 섹션 배너 행; 얼룩말 줄무늬; 제약 행에 문자 수 안내; 동적 행에 색상이 지정된 셀과 "{{…}} 부분 유지" 경고; 마지막 페이지에 다음 단계 및 승인 테이블. 파일을 다시 열어 행 수가 일치하고 수정/참고 사항 컬럼이 비어 있는지 확인합니다.

절대 "수정 제안" 또는 "참고 사항"을 미리 채우지 마십시오. 리뷰어의 판단이 핵심입니다.

사용자가 1단계에서 Word 주석/변경 추적을 선택한 경우에도 이 문서를 빌드하고(Ref 코드가 변경 추적을 추적 가능하게 함) 수정 사항에 수동 매칭이 필요할 수 있음을 알리십시오.

6단계 — 전달하기 전에 살펴보기

구조적 검사는 데이터가 올바르다는 것을 증명하지만, 읽기 좋다는 것을 증명하지는 않습니다. 렌더링하여 실제로 확인합니다: 표지, 설정/내비게이션 페이지, 가장 밀집된 긴 단락 페이지(폭이 실패하는 곳).

soffice --headless --convert-to pdf --outdir <dir> <file>.docx
pdftoppm -png -r 80 -f <n> -l <n> <file>.pdf <prefix>

PNG를 열어 Read로 확인합니다. 이러한 도구가 없으면 시각적 검사가 수행되지 않았음을 명확히 말합니다.

7단계 — 소스 결함 별도 보고

모든 코드 줄을 읽으면 실제 버그가 드러납니다. 별도 섹션(또는 별도의 source-defects.md)에 보고합니다. 이는 코드 문제이지 문구 문제가 아닙니다. 일반적인 예:

• 렌더링된 HTML에 리터럴 Markdown이 표시됨(**bold**가 페이지에 나타남)
• 존재하지 않는 ID에 대한 앵커 링크
• 존재하지만 실행 가능한 내용이 없는 섹션에 대한 링크
• 페이지/경로가 없는 템플릿(카피에 접근 불가)
• 템플릿을 재정의하는 사용자 정의 템플릿 뒤에 있는 고아 CMS 콘텐츠
• 재사용 가능한 템플릿에 하드코딩된 플레이스홀더 값

보고하기 전에 각각 직접 확인하십시오 — 대상 ID를 grep하고 템플릿을 엽니다. 에이전트는 이를 과장합니다. 한 번 "깨진 앵커"로 보였던 것이 실제로는 유효한 대상이 있었지만 해당 섹션에 실행할 작업이 없었던 경우가 있었습니다. 실제로 무엇이 있는지 파일과 줄 번호와 함께 설명하십시오.

8단계 — 전달

.docx 파일을 사용자에게 보냅니다. 간략히 언급: 총 항목 및 페이지 수, 취해진 범위 결정, 매니페스트 CSV(반환된 수정 사항을 Ref별로 적용하기 위해 — 리뷰어의 손에 닿지 않도록 유지), 수용한 검증 잔여물과 그 이유, 결함 목록, 저장소에 해당 규칙이 있는 경우 이슈 우선 주의사항.

반환된 수정 사항 적용 (사용자가 돌아왔을 때)

반환된 .docx 테이블 행(Ref + 수정 제안 + 참고 사항)을 읽고, copy-review-manifest.csv와 Ref별로 조인하여 각 비어 있지 않은 수정 사항에 대해 file의 line 근처에서 text를 찾아 교체합니다. 제약 행에서 chars를 크게 초과하는 수정 사항이나 {{…}} 표현식을 삭제하는 수정 사항은 조용히 자르지 말고 플래그를 지정합니다. 저장소를 편집하기 전에 사용자에게 계획된 변경 사항을 보여줍니다.