본문으로 건너뛰기
cccskills
무료GitHub에 공개

docs-link-audit

Docs 사이트 (`site/` Next.js) 의 본문/JSX/markdown 링크 audit. broken 내부 링크 탐지, build-time copy 인지, 옵트인 HTTP probe. 신규 페이지 추가 / slug 이전 / chapter 삭제 후 회귀 방지. Triggered by "broken link", "404", "docs link", "hyperlink", "링크 점검", "링크 깨짐", "audit links", "link checker" 키워드.

한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.

mangowhoiscloud/geode
설치 방법 보기

포함된 파일(1)

  • SKILL.md5.9 KB

SKILL.md(원문)

설치하기 전에 에이전트에게 전달되는 지시 내용을 확인할 수 있습니다.

Docs Link Audit

site/ Next.js docs 사이트의 모든 본문 링크를 정적 + 옵션 HTTP 로 검사한다. scripts/check_docs_links.py 가 본 워크플로의 1차 도구.

언제 가동되는가

신규 페이지 추가 / chapter 삭제 / slug 이전 / cross-link 개정 후. 또한 사용자가 "404 뜨는 부분 잡자" / "링크 깨진 것 확인해줘" 같은 요청을 했을 때.

1차 도구 — scripts/check_docs_links.py

$ python3 scripts/check_docs_links.py              # 정적 audit (1초)
$ python3 scripts/check_docs_links.py --http       # + 외부 reachability (~10초)
$ python3 scripts/check_docs_links.py --quiet      # broken 만 출력 (CI 적합)

분류 4 종

Category매칭 패턴검증 방법
internal /docs/...href="/docs/runtime/foo"site/src/app/docs/**/page.tsx slug set 과 차집합
internal /<other>.../portfolio, /petri-bundle/, /llms.txtapp route + site/public/ asset + build-time copy 와 대조
anchor #sectionhref="#tier-3"같은 page.tsx 의 id="..." 와 대조
external https://<a href="https://github.com/...">--http 옵트인 시 HEAD/GET, concurrency 8, 8s timeout, 200/3xx OK

특이 처리

  • /geode/ deploy basepath 정규화 — /geode/docs/foo 도 source-side /docs/foo 와 매칭
  • Build-time copy 인지 — .github/workflows/pages.yml 의 docs/self-improving/petri-bundle/ → site/out/petri-bundle/ copy step 알기 때문에 /petri-bundle/ 가 source 에 없어도 OK
  • ${...} 보간 + relative URL → unresolved 로 분리 (broken 아님)
  • 스킴 스킵 — mailto:, tel:, javascript:, data:, blob:
  • requests 미설치 시 명시한 --http는 실패한다. 검사를 생략하고 성공으로 표시하거나 성공 receipt를 쓰지 않는다.

Exit codes — CI guard 가능

Code의미
0broken 없음
11+ broken 발견 또는 명시한 HTTP 검사의 의존성 부재
2argparse / IO 에러

Workflow — 새 페이지 또는 cross-link 수정 후

1. 변경 → 본 변경이 새 페이지 추가 / slug 이전 / chapter 삭제 / cross-link 갱신 중 하나
        ↓
2. python3 scripts/check_docs_links.py
        ↓
3. broken 0 → 내부 정적 링크 검사 통과; 외부·동적 링크 성공과 구분
   broken N → 메시지의 file:line 으로 이동 + slug 정정
        ↓
4. (선택) --http 도 돌려서 외부 URL reachability 확인
        ↓
5. PR cascade — fix(docs): broken link N 종 정정 (M 사이트)

잘못된 link 의 흔한 원인

패턴발생 시점해결책
Chapter 삭제 후 cross-link leftover옛 build/ 챕터 삭제했는데 다른 페이지가 /docs/build/add-domain 참조이전 destination 확인 후 새 slug 로 교체 — sitemap.ts 의 새 entry 가 1차 단서
Section 이전/docs/ops/observability → /docs/verification/observability 로 옮겼는데 cross-link 갱신 누락동일
Slug 오타페이지 처음 작성 시 디렉터리 명 오타typo 수정
External URL 만료외부 doc 의 link 가 404 (e.g. dev portal 페이지 이전)--http 가 잡음. 새 URL 또는 archive.org 로 교체
아직 공개되지 않은 대상새 문서의 blob/main 또는 배포 전 버전 태그가 PR에서 404이미 공개된 commit에 문서를 고정하거나 릴리스 목록을 연결. 미래 배포를 검사 예외로 숨기지 않음

CI wiring

.github/workflows/pages.yml already runs the static check and a lychee check on built HTML, including external URLs. Inspect that workflow before proposing another job. Local --http probes remain opt-in; dynamic URLs need rendered output or direct inspection. None of these checks authorizes another monitor.

실제 case study

날짜broken 수정정 방식
2026-05-16 PR #11573 broken × 6 ref site모든 destination 이 sitemap 에 다른 slug 로 존재. 단순 경로 교체
2026-05-16 PR #11610 (script 도입)check_docs_links.py 추가 + 위 case study 결과 0 broken 측정

PR #1157 의 3 broken:

  • /docs/build/add-domain → /docs/runtime/domains (build/ chapter D 스프린트에서 삭제됨)
  • /docs/build/add-tool → /docs/runtime/tools/protocol
  • /docs/ops/observability → /docs/verification/observability (section 이전)

ad-hoc grep 으로 잡았지만 본 스크립트가 다음번부터는 1 명령으로 검출.

한계 + 알려진 false positive

항목한계
Dynamic href={url}변수 보간된 link 는 정적 분석 불가 → unresolved (broken 아님)
External URL rate-limit / login wall--http 가 401/403 받으면 broken 으로 분류 — 일부 사이트 (Anthropic dev portal 등) 가 anti-bot 으로 403 가능
Anchor 검사 단위같은 page.tsx 내 anchor 만 검증. 크로스 페이지 anchor /docs/foo#bar 는 /docs/foo 만 OK 면 통과 (anchor 자체는 검증 안 됨)
정규식·코드 예시리터럴 패턴이 링크 후보로 잡힐 수 있으므로 원문을 확인한다. 고정 파일·행 번호나 과거 건수만으로 무시하지 않는다.

관련 skill

  • geode-changelog — 기능 변경을 함께 포함할 때 기록; 문서 전용 수정은 생략
  • geode-gitflow — 요청 범위에 포함된 PR·병합 단계에 적용
  • frontier-harness-research — peer comparison 표가 외부 URL 다수 → --http audit 가치 큼

리뷰

아직 리뷰가 없습니다. 사용해 본 소감을 남겨 주세요.

댓글

로그인 없이 쓸 수 있습니다. 사용 후기, 질문, 작동하지 않은 환경 등을 편하게 남겨 주세요.

아직 댓글이 없습니다. 첫 댓글을 남겨 보세요.

보내면 바로 공개됩니다. 이메일 주소나 전화번호 같은 개인 정보는 쓰지 마세요. URL은 2개까지입니다.

0 / 1,000자

이 양식은 reCAPTCHA로 보호되며 Google 개인정보처리방침 및 서비스 약관이 적용됩니다.

같은 저장소의 스킬

agent-anti-pattern

무료

Audit agent runtimes and their tests for lifecycle inference, capability overload, context pollution, correlated verification, prompt-only control, false success, dead compatibility paths, test-only seams, and complexity without contribution. Use for whole-repository agent audits, slop or dead-code triage, test contribution reviews, large refactors, tool/context simplification, and cleanup requests that need proof before deleting code or tests.

한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.

mangowhoiscloud/geode152026년 10월 16일 업데이트

agent-ops-debugging

무료

Diagnose agent operational failures through default-policy checks, multi-gap analysis, explicit service ownership, request-context lifetime, and degradation-versus-correctness checks.

한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.

mangowhoiscloud/geode152026년 10월 16일 업데이트

agent-world-benchmark

무료

Align, run, audit, and publish GEODE benchmark comparisons against Agent-World arXiv 2604.18292v1 across MCP-Mark, BFCL V4, and tau2-bench. Use for Agent-World or AgentWorld comparison requests, cross-suite agent benchmark design, Tau2 comparator/profile diagnosis, paired thin-runtime-versus-GEODE experiments, mean-accuracy@8 replication, or benchmark comparability and artifact reviews.

한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.

mangowhoiscloud/geode152026년 10월 16일 업데이트

anti-deception-checklist

무료

Verification checklist to prevent fake success. Detects test deletion/disabling, coverage regression, lint bypass, secret exposure. Triggered by "deception", "fake" ("가짜"), "fake success", "verification" ("검증"), "checklist" ("체크리스트"), "deletion detection" ("삭제 탐지"), "regression" keywords.

한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.

mangowhoiscloud/geode152026년 10월 16일 업데이트

architecture-patterns

무료

Implement proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design. Use when architecting complex backend systems or refactoring existing applications for better maintainability.

한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.

mangowhoiscloud/geode152026년 10월 16일 업데이트

arxiv-digest

무료

Auto-search and summarize latest AI/agent papers.

한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.

mangowhoiscloud/geode152026년 10월 16일 업데이트

mangowhoiscloud의 스킬 모두 보기

이 스킬의 문제 신고