Claude Skill

docs-sync

코드·설정·프리셋 변경 뒤 문서를 현행화한다. "문서 현행화", "README 갱신", "문서 최신화" 요청 시, 그리고 동작·경로·버전·수치를 바꾼 PR 을 올리기 직전에 사용. 문서의 주장을 실제 코드·명령 출력·공식문서와 대조해 정정하고, 다국어 짝 파일을 함께 갱신한다.

LLM Mart · 0 points · 23 views 86 listing impressions 0 install-command copies
Download LeeYudok-agents-scaffold-.claude_skills_docs-sync-6a7476d.zip · 16 KB

Install

skills CLI npx skills add https://github.com/LeeYudok/agents-scaffold/tree/main/.claude/skills/docs-sync
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install leeyudok-agents-scaffold@llmmart
Git git clone https://github.com/LeeYudok/agents-scaffold.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole leeyudok/agents-scaffold collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

docs-sync

코드는 빌드와 테스트가 지켜 주지만 문서는 아무도 지켜 주지 않는다. 디렉터리를 지우거나 옮기면 그 경로를 가리키던 지침·README·규칙이 조용히 거짓이 된다. 에이전트는 그 문서를 읽고 없는 파일을 찾거나 지운 명령을 다시 돌린다.

이 스킬은 바뀐 실제에 문서를 맞춘다. 판단 기준은 언제나 코드·설정·파일시스템과 실제 실행 결과다. 문서끼리 맞추는 것이 아니다.

원칙

  • 주장 단위로 검증한다. 문서를 "읽고 자연스러운지" 보는 게 아니라, 문장이 담은 검증 가능한 주장(경로·버전·수치·동작·기본값)을 뽑아 실제와 대조한다.
  • 근거 없이 고치지 않는다. 파일:라인, 명령 출력, 공식문서 URL 중 하나가 있어야 한다. 확인 못 한 건 지우지 말고 "미검증"으로 명시한다 — 조용히 삭제하면 정보가 사라진다.
  • 낙관적 서술 금지. 부분만 동작하면 "동작한다"고 쓰지 않는다. 되는 범위와 안 되는 범위를 나눠 쓴다.

경계

대상 맡는 스킬
에이전트 영속 메모리의 사실 감사 memory-factcheck (이 스킬은 경로 참조만 같이 고친다)
AGENTS.yaml 처음 세팅·구조 변경 yd-agents-yaml (이 스킬은 기존 값이 실제와 맞는지만 본다)
프로젝트 전용 대조표 레포에 *-doc-sync 같은 프로젝트 스킬이 있으면 그 대조표를 먼저 따른다
고친 문장·보고서·이슈/MR 본문의 문장 정리 yd-writer-kr (이 스킬은 무엇을 고칠지 정하고, 문장은 그 규칙으로 쓴다)
이슈·커밋·MR 레포 워크플로(AGENTS.md). GitLab 에이전트 계정을 쓰면 옵트인 yd-git-ship

워크플로

1. 범위 정하기

무엇이 바뀌었는지부터 확정한다. 추측으로 범위를 넓히지 않는다.

git log --oneline -15                          # 기준점 찾기
git diff --name-status -M <기준> HEAD | head    # 무엇이 지워지고 옮겨졌나
  • 기준점은 사용자가 말한 커밋·MR, 없으면 문서를 마지막으로 맞춘 머지 직전 커밋이다.
  • 레포의 프로젝트 스킬·AGENTS.md·.claude/rules/ 에 문서 갱신 규칙(어떤 코드가 바뀌면 어떤 문서를 고치는지)이 있으면 읽고 그대로 따른다.

2. 드리프트 뽑기 — 스크립트 먼저

손 grep 보다 스크립트가 먼저다. 사람이 짠 정규식은 하위 프로젝트의 같은 이름 경로 (ews-v3/web/src 를 가리키는 web/src)를 지운 경로로 오인한다.

S=<이 스킬>/scripts/find_stale_refs.py
python3 $S --removed-since <기준>            # 지워지거나 옮겨진 경로를 가리키는 줄
python3 $S                                  # 전체 존재 검사(첫 조각이 레포에 있는 경로만)
python3 $S --exclude 'model-source/*' --json  # 보존본 제외, 기계 처리용
  • 추적 중인 문서(*.md·*.yaml·*.toml·AGENTS*·CLAUDE* 등)만 본다. 코드의 경로 문자열은 빌드·테스트 몫이다.

  • 전체 존재 검사는 첫 경로 조각이 지금 레포에 있는 토큰만 본다(다른 레포 경로 소음을 줄이려고). 최상위 폴더를 통째로 지웠다면 반드시 --removed-since 로 잡는다.

  • 레포 어딘가에 실제로 있는 경로(하위 프로젝트 기준 상대경로, docs/12 같은 번호 축약)는 빼고 보고한다. 옮겨진 경로는 renamed -> 새 경로 로 알려 준다.

  • 종료 코드는 current 가 있으면 1, history 만 남으면 0, git·인자 오류는 2 다. 1 은 스크립트가 고장 났다는 뜻이 아니라 고칠 줄이 있다는 뜻이다. --strict 는 history 도 1 로 센다.

  • 스크립트가 못 잡는 드리프트는 따로 확인한다. 서술 종류마다 근거 원천이 정해져 있고, 문서끼리 맞추지 않는다.

    서술 근거 원천
    환경변수 이름 설정을 읽는 코드(os.Getenv·config 로더), .env.example
    포트·컨테이너·헬스체크 Quadlet *.container·compose 의 HealthCmd·PublishPort, 실제 podman ps/docker ps
    실행 명령·CI 잡 package.json scripts, Makefile, CI 설정 파일
    의존성·버전 go.mod·package.json·lock 파일
    개수·수치("테이블 37개") 실제 조회 결과와 그 날짜(DB 쿼리·find·grep -c)
    트래커 동작(자동 클로즈 등) 직전 이슈·MR 의 실제 state
    CLI 플래그·기본값 <cmd> --help 실행 결과(문서 인용 금지)
    도구 버전 <cmd> --version 실측 + 실측 일자 병기
    동작("자동 로드한다") 해당 도구 공식문서 URL. 없으면 "문서 근거 없음"으로 표기
    게이트 동작 실제로 실행해서 exit code 확인

    특히 낡기 쉬운 것: 디렉터리 트리 블록(신규 산출물 누락 — 링크가 아니라 코드블록 안 텍스트라 링크 체커도 못 잡는다), 버전 표기, "자동으로 ~한다" 류 동작 서술, 지원 매트릭스.

  • 고친 서술은 레포 전체에서 같은 서술을 다시 찾는다(git grep). zsh 에서 grep --include 를 쓰면 glob 을 따옴표로 감싼다(--include='*.md') — 안 그러면 no matches found 로 멈춘다.

  • AGENTS.yaml 이 있으면 레포의 검증기(scripts/check-agents-yaml.sh)를 돌린다.

레포별 범위 — AGENTS.yaml 의 x-doc-sync

레포마다 「고치지 않는 시점 기록」과 「아예 안 보는 경로」가 다르다. 레포 루트 AGENTS.yaml 에 적어 두면 스크립트가 읽는다(yd-agents-yaml 규약의 x- 섹션).

x-doc-sync:
  history:              # 찾아도 history 로만 센다 — 고치지 않는 기록
    - CHANGELOG.md
    - docs/superpowers/{plans,specs}/**
    - .claude/memory/archive/**
  exclude:              # 훑지 않는다 — 원본 사본·생성 데이터
    - data/manual/**

*·**(둘 다 / 를 넘는다)·{a,b} 를 쓴다. 섹션이 없으면 기본값(CHANGELOG·archive/ 는 이력, 잠금 파일·node_modules 등은 제외)으로 돈다. 레포에 이 섹션을 처음 넣을 때는 AGENTS.md 에 「문서 현행화는 docs-sync 를 쓴다」 한 줄도 같이 둔다. PyYAML 이 없어도 위 모양(블록 목록·흐름 목록)은 읽는다. 깨진 AGENTS.yaml 은 경고만 내고 기본값으로 돈다.

3. 분류 — 현행 지시와 시점 기록을 가른다

찾은 줄을 셋으로 나눈다. 스크립트의 current/history 는 낱말 기반 추정이니 줄을 직접 읽고 정한다.

분류 예 처리
현행 지시 "서버는 backend/cmd/server 로 띄운다", 규칙 파일의 paths: 실제에 맞게 고친다. 대상이 없어졌으면 문장을 지우거나 새 위치로 바꾼다
시점 기록 CHANGELOG, "2026-09-21 커밋 e59d98b 기준", 이슈 번호가 붙은 결정 기록, 지난 계획·스펙(plans/·specs/), 실행 로그(runs/), 메모리 archive/, 보존용 원본 사본 고치지 않는다. 현행 지시처럼 읽혀 오해를 부르면 "(#N 에서 제거)" 같은 표지만 붙인다
생성물 스크립트가 만든 HTML·SVG·코드 직접 고치지 않는다. 생성기(템플릿·스크립트)를 고치고 다시 돌린다
  • 설계 결정 기록(ADR·D-엔트리)이 있는 레포에서 구조가 바뀌었으면 결정 항목을 하나 더하고, 옛 서술은 그 항목을 가리키게 표시한다. 옛 결정 본문을 다시 쓰지 않는다.
  • 메모리 파일은 경로 참조만 고치고, 사실 자체의 낡음은 memory-factcheck 로 넘긴다.

4. 고치기

  • 근거를 확인한 것만 고친다. 새 경로·명령·값은 실제 파일을 열거나 명령을 돌려 확인한 뒤 적는다. 확인 못 한 줄은 고치지 말고 보고서의 「확인 필요」에 둔다.
  • 지운 기능을 설명하던 절은 통째로 지운다. 빈 껍데기 문장("~는 없다")을 여러 군데 남기지 말고, 사라진 사실은 한 곳(README·결정 기록)에만 남긴다.
  • 문서 갱신 규칙이 있는 파일(규칙 표, 스킬 목록, 인덱스)은 표와 실제 파일 목록을 함께 맞춘다.
  • 고친 문장은 항상 yd-writer-kr 로 정리한다. 경로만 바꾸면 앞뒤 문장이 어긋나기 쉽다. 고친 줄과 그 문단을 그 스킬 규칙으로 다시 읽고 다듬는다. 문체는 그 문서의 것을 따르고, 고치지 않은 문단까지 손대지 않는다.
  • 다국어·짝 파일은 같은 커밋에서 함께 고친다(필수). 한쪽만 고치면 나머지가 stale 이 되는데 어떤 게이트에도 안 걸린다. ls README*.md 로 언어판 전량을, presets/lang/en/ 같은 언어 오버레이가 있으면 대응 파일까지 고친다. 번역이 아니라 같은 사실의 각 언어판이라 수치·버전·경로·표 구조는 동일하게 둔다. 언어마다 원문이 달라 일괄 치환이 깨지므로 파일마다 grep -n 으로 교체 대상을 먼저 확인한다.
  • 고친 파일이 많으면 파일 범위를 겹치지 않게 나눠 서브에이전트에 맡겨도 된다. 사실 업데이트(예: 운영 철거 완료)가 생기면 즉시 모든 서브에이전트에 전달한다.

5. 검증

python3 $S --removed-since <기준>   # current 0 이거나, 남은 줄마다 둔 이유가 있다
<레포 검증기들>                      # AGENTS.yaml 검증기, 링크 검사(python3 .claude/scripts/knowledge_graph.py --check) 등
<레포 빌드·테스트>                   # 문서와 함께 바뀐 스크립트·설정이 있으면

남은 current 는 줄마다 왜 두는지(다른 레포 경로, 의도된 이력) 한 줄로 적는다.

6. 보고

채팅에는 짧게, 상세는 이슈·MR 본문에 둔다. 보고서와 이슈·MR 본문도 yd-writer-kr 로 쓴다.

## 문서 현행화 — <기준>..HEAD
- 고친 것: <파일 N개> — 주장마다 `이전 → 이후 + 근거`("README 를 갱신했다" 같은 요약만 남기지 않는다)
- 기록으로 둔 것: <파일·줄> — <이유>
- 확인 필요: <줄> — <무엇을 확인해야 하는지>
- 대조하지 못한 범위: <폴더·문서 종류> — <이유(접근 불가·근거 원천 없음·시간)>
- 검증: find_stale_refs current <n>건(사유 명시), <검증기> 통과

커밋·MR 은 레포 워크플로(이슈 → 브랜치 → PR/MR)로 올린다. 문서 현행화는 코드 변경과 같은 MR 에 넣는 것이 원칙이다(코드를 바꾼 MR 이 문서도 같이 고친다). 이미 머지된 변경을 뒤따라 맞출 때만 별도 이슈로 연다.

완료 조건

  • find_stale_refs.py --removed-since <기준> 의 current 가 0 이거나, 남은 줄마다 둔 이유가 보고서에 있다.
  • 고친 서술마다 근거 파일·명령 결과를 확인했다.
  • 시점 기록과 생성물은 직접 고치지 않았다.
  • 고친 문장과 보고서·이슈·MR 본문을 yd-writer-kr 로 정리했다.
  • 다국어·언어 오버레이 짝 파일이 같은 커밋에 들어 있다.
  • 레포의 문서 검증기(링크 체커 0 broken 포함)와, 함께 바뀐 스크립트의 테스트가 통과한다.
  • 보고서·MR 본문에 대조하지 못한 범위를 적었다(없으면 「없음」). 빠뜨린 폴더가 다음 드리프트가 된다.

Learned warnings

  • (2026-10-24) agents-scaffold 의 docs-sync 와 doksam-skills 의 yd-doc-sync 를 하나로 합쳤다. 드리프트 추출(find_stale_refs.py)·현행/기록 분류는 yd-doc-sync, 주장 단위 대조·"미검증" 표기·다국어 짝 파일 동시 갱신·링크 체커 게이트는 docs-sync 에서 왔다 (agents-scaffold #78).
  • (2026-10-24) 낡은 서술을 삭제로 처리하면 "왜 없어졌는지" 추적이 끊긴다 — 실측 일자와 함께 "미검증"으로 남기는 편이 낫다.
Files (agents-scaffold)
  • scripts
    • find_stale_refs.py 15.3 KB
      Loading…
  • tests
    • claims.json 3.2 KB
      Loading…
    • test_find_stale_refs.py 10.8 KB
      Loading…
  • SKILL.md 12.7 KB
    ---
    name: docs-sync
    description: 문서 현행화(docs-sync) — 코드·구성이 바뀐 뒤(디렉터리 삭제·이동, 포트·명령·의존성 변경, 큰 리팩터링 머지) 에이전트 지침(AGENTS.md·CLAUDE.md)·README·규칙(.claude/rules)·스킬·docs 가 실제와 어긋난 곳을 찾아 고친다. 지워지거나 옮겨진 경로를 가리키는 참조를 스크립트로 뽑고, 현행 지시와 시점 기록을 갈라 현행만 고친다. "문서 현행화", "문서 최신화", "README 갱신", "문서 드리프트 확인", "docs-sync", "남은 참조 정리" 요청과, 동작·경로·버전·수치를 바꾼 PR 을 올리기 직전에 쓴다. 문서의 주장을 실제와 대조하고 다국어 짝 파일을 함께 고친다. 메모리 감사는 memory-factcheck, AGENTS.yaml 세팅은 yd-agents-yaml 이 맡는다.
    ---
    
    # docs-sync
    
    코드는 빌드와 테스트가 지켜 주지만 문서는 아무도 지켜 주지 않는다. 디렉터리를
    지우거나 옮기면 그 경로를 가리키던 지침·README·규칙이 조용히 거짓이 된다.
    에이전트는 그 문서를 읽고 없는 파일을 찾거나 지운 명령을 다시 돌린다.
    
    이 스킬은 **바뀐 실제에 문서를 맞춘다**. 판단 기준은 언제나 코드·설정·파일시스템과
    실제 실행 결과다. 문서끼리 맞추는 것이 아니다.
    
    ## 원칙
    
    - **주장 단위로 검증한다.** 문서를 "읽고 자연스러운지" 보는 게 아니라, 문장이 담은
      **검증 가능한 주장**(경로·버전·수치·동작·기본값)을 뽑아 실제와 대조한다.
    - **근거 없이 고치지 않는다.** 파일:라인, 명령 출력, 공식문서 URL 중 하나가 있어야 한다.
      확인 못 한 건 지우지 말고 **"미검증"으로 명시**한다 — 조용히 삭제하면 정보가 사라진다.
    - **낙관적 서술 금지.** 부분만 동작하면 "동작한다"고 쓰지 않는다. 되는 범위와 안 되는
      범위를 나눠 쓴다.
    
    ## 경계
    
    | 대상 | 맡는 스킬 |
    |---|---|
    | 에이전트 영속 메모리의 사실 감사 | `memory-factcheck` (이 스킬은 경로 참조만 같이 고친다) |
    | `AGENTS.yaml` 처음 세팅·구조 변경 | `yd-agents-yaml` (이 스킬은 기존 값이 실제와 맞는지만 본다) |
    | 프로젝트 전용 대조표 | 레포에 `*-doc-sync` 같은 프로젝트 스킬이 있으면 **그 대조표를 먼저** 따른다 |
    | 고친 문장·보고서·이슈/MR 본문의 문장 정리 | `yd-writer-kr` (이 스킬은 무엇을 고칠지 정하고, 문장은 그 규칙으로 쓴다) |
    | 이슈·커밋·MR | 레포 워크플로(AGENTS.md). GitLab 에이전트 계정을 쓰면 옵트인 `yd-git-ship` |
    
    ## 워크플로
    
    ### 1. 범위 정하기
    
    무엇이 바뀌었는지부터 확정한다. 추측으로 범위를 넓히지 않는다.
    
    ```bash
    git log --oneline -15                          # 기준점 찾기
    git diff --name-status -M <기준> HEAD | head    # 무엇이 지워지고 옮겨졌나
    ```
    
    - 기준점은 사용자가 말한 커밋·MR, 없으면 문서를 마지막으로 맞춘 머지 직전 커밋이다.
    - 레포의 프로젝트 스킬·`AGENTS.md`·`.claude/rules/` 에 문서 갱신 규칙(어떤 코드가 바뀌면
      어떤 문서를 고치는지)이 있으면 읽고 그대로 따른다.
    
    ### 2. 드리프트 뽑기 — 스크립트 먼저
    
    손 grep 보다 스크립트가 먼저다. 사람이 짠 정규식은 하위 프로젝트의 같은 이름 경로
    (`ews-v3/web/src` 를 가리키는 `web/src`)를 지운 경로로 오인한다.
    
    ```bash
    S=<이 스킬>/scripts/find_stale_refs.py
    python3 $S --removed-since <기준>            # 지워지거나 옮겨진 경로를 가리키는 줄
    python3 $S                                  # 전체 존재 검사(첫 조각이 레포에 있는 경로만)
    python3 $S --exclude 'model-source/*' --json  # 보존본 제외, 기계 처리용
    ```
    
    - 추적 중인 문서(`*.md`·`*.yaml`·`*.toml`·`AGENTS*`·`CLAUDE*` 등)만 본다. 코드의 경로
      문자열은 빌드·테스트 몫이다.
    - 전체 존재 검사는 첫 경로 조각이 지금 레포에 있는 토큰만 본다(다른 레포 경로 소음을 줄이려고).
      최상위 폴더를 통째로 지웠다면 반드시 `--removed-since` 로 잡는다.
    - 레포 어딘가에 실제로 있는 경로(하위 프로젝트 기준 상대경로, `docs/12` 같은 번호 축약)는
      빼고 보고한다. 옮겨진 경로는 `renamed -> 새 경로` 로 알려 준다.
    - 종료 코드는 `current` 가 있으면 1, `history` 만 남으면 0, git·인자 오류는 2 다.
      1 은 스크립트가 고장 났다는 뜻이 아니라 고칠 줄이 있다는 뜻이다. `--strict` 는 `history` 도 1 로 센다.
    - 스크립트가 못 잡는 드리프트는 따로 확인한다. 서술 종류마다 근거 원천이 정해져 있고,
      **문서끼리 맞추지 않는다**.
    
      | 서술 | 근거 원천 |
      |---|---|
      | 환경변수 이름 | 설정을 읽는 코드(`os.Getenv`·config 로더), `.env.example` |
      | 포트·컨테이너·헬스체크 | Quadlet `*.container`·compose 의 `HealthCmd`·`PublishPort`, 실제 `podman ps`/`docker ps` |
      | 실행 명령·CI 잡 | `package.json` scripts, `Makefile`, CI 설정 파일 |
      | 의존성·버전 | `go.mod`·`package.json`·lock 파일 |
      | 개수·수치("테이블 37개") | 실제 조회 결과와 그 날짜(DB 쿼리·`find`·`grep -c`) |
      | 트래커 동작(자동 클로즈 등) | 직전 이슈·MR 의 실제 state |
      | CLI 플래그·기본값 | `<cmd> --help` 실행 결과(문서 인용 금지) |
      | 도구 버전 | `<cmd> --version` 실측 + **실측 일자 병기** |
      | 동작("자동 로드한다") | 해당 도구 **공식문서 URL**. 없으면 "문서 근거 없음"으로 표기 |
      | 게이트 동작 | 실제로 실행해서 exit code 확인 |
    
      특히 낡기 쉬운 것: **디렉터리 트리 블록**(신규 산출물 누락 — 링크가 아니라 코드블록 안
      텍스트라 링크 체커도 못 잡는다), **버전 표기**, **"자동으로 ~한다" 류 동작 서술**, **지원 매트릭스**.
    
    - 고친 서술은 레포 전체에서 같은 서술을 다시 찾는다(`git grep`). zsh 에서 `grep --include`
      를 쓰면 glob 을 따옴표로 감싼다(`--include='*.md'`) — 안 그러면 `no matches found` 로 멈춘다.
    - `AGENTS.yaml` 이 있으면 레포의 검증기(`scripts/check-agents-yaml.sh`)를 돌린다.
    
    #### 레포별 범위 — `AGENTS.yaml` 의 `x-doc-sync`
    
    레포마다 「고치지 않는 시점 기록」과 「아예 안 보는 경로」가 다르다. 레포 루트
    `AGENTS.yaml` 에 적어 두면 스크립트가 읽는다(`yd-agents-yaml` 규약의 `x-` 섹션).
    
    ```yaml
    x-doc-sync:
      history:              # 찾아도 history 로만 센다 — 고치지 않는 기록
        - CHANGELOG.md
        - docs/superpowers/{plans,specs}/**
        - .claude/memory/archive/**
      exclude:              # 훑지 않는다 — 원본 사본·생성 데이터
        - data/manual/**
    ```
    
    `*`·`**`(둘 다 `/` 를 넘는다)·`{a,b}` 를 쓴다. 섹션이 없으면 기본값(CHANGELOG·`archive/`
    는 이력, 잠금 파일·`node_modules` 등은 제외)으로 돈다. 레포에 이 섹션을 처음 넣을 때는
    `AGENTS.md` 에 「문서 현행화는 `docs-sync` 를 쓴다」 한 줄도 같이 둔다.
    PyYAML 이 없어도 위 모양(블록 목록·흐름 목록)은 읽는다. 깨진 `AGENTS.yaml` 은 경고만 내고 기본값으로 돈다.
    
    ### 3. 분류 — 현행 지시와 시점 기록을 가른다
    
    찾은 줄을 셋으로 나눈다. 스크립트의 `current`/`history` 는 낱말 기반 추정이니
    **줄을 직접 읽고** 정한다.
    
    | 분류 | 예 | 처리 |
    |---|---|---|
    | 현행 지시 | "서버는 `backend/cmd/server` 로 띄운다", 규칙 파일의 `paths:` | 실제에 맞게 고친다. 대상이 없어졌으면 문장을 지우거나 새 위치로 바꾼다 |
    | 시점 기록 | CHANGELOG, "2026-09-21 커밋 `e59d98b` 기준", 이슈 번호가 붙은 결정 기록, 지난 계획·스펙(`plans/`·`specs/`), 실행 로그(`runs/`), 메모리 `archive/`, 보존용 원본 사본 | **고치지 않는다.** 현행 지시처럼 읽혀 오해를 부르면 "(#N 에서 제거)" 같은 표지만 붙인다 |
    | 생성물 | 스크립트가 만든 HTML·SVG·코드 | 직접 고치지 않는다. 생성기(템플릿·스크립트)를 고치고 다시 돌린다 |
    
    - 설계 결정 기록(ADR·D-엔트리)이 있는 레포에서 구조가 바뀌었으면 결정 항목을 하나
      더하고, 옛 서술은 그 항목을 가리키게 표시한다. 옛 결정 본문을 다시 쓰지 않는다.
    - 메모리 파일은 경로 참조만 고치고, 사실 자체의 낡음은 `memory-factcheck` 로 넘긴다.
    
    ### 4. 고치기
    
    - **근거를 확인한 것만 고친다.** 새 경로·명령·값은 실제 파일을 열거나 명령을 돌려 확인한
      뒤 적는다. 확인 못 한 줄은 고치지 말고 보고서의 「확인 필요」에 둔다.
    - 지운 기능을 설명하던 절은 통째로 지운다. 빈 껍데기 문장("~는 없다")을 여러 군데
      남기지 말고, 사라진 사실은 한 곳(README·결정 기록)에만 남긴다.
    - 문서 갱신 규칙이 있는 파일(규칙 표, 스킬 목록, 인덱스)은 표와 실제 파일 목록을 함께 맞춘다.
    - **고친 문장은 항상 `yd-writer-kr` 로 정리한다.** 경로만 바꾸면 앞뒤 문장이 어긋나기
      쉽다. 고친 줄과 그 문단을 그 스킬 규칙으로 다시 읽고 다듬는다. 문체는 그 문서의 것을
      따르고, 고치지 않은 문단까지 손대지 않는다.
    - **다국어·짝 파일은 같은 커밋에서 함께 고친다(필수).** 한쪽만 고치면 나머지가 stale 이
      되는데 어떤 게이트에도 안 걸린다. `ls README*.md` 로 언어판 전량을, `presets/lang/en/` 같은
      언어 오버레이가 있으면 대응 파일까지 고친다. 번역이 아니라 **같은 사실의 각 언어판**이라
      수치·버전·경로·표 구조는 동일하게 둔다. 언어마다 원문이 달라 일괄 치환이 깨지므로 파일마다
      `grep -n` 으로 교체 대상을 먼저 확인한다.
    - 고친 파일이 많으면 파일 범위를 겹치지 않게 나눠 서브에이전트에 맡겨도 된다. 사실
      업데이트(예: 운영 철거 완료)가 생기면 즉시 모든 서브에이전트에 전달한다.
    
    ### 5. 검증
    
    ```bash
    python3 $S --removed-since <기준>   # current 0 이거나, 남은 줄마다 둔 이유가 있다
    <레포 검증기들>                      # AGENTS.yaml 검증기, 링크 검사(python3 .claude/scripts/knowledge_graph.py --check) 등
    <레포 빌드·테스트>                   # 문서와 함께 바뀐 스크립트·설정이 있으면
    ```
    
    남은 `current` 는 줄마다 왜 두는지(다른 레포 경로, 의도된 이력) 한 줄로 적는다.
    
    ### 6. 보고
    
    채팅에는 짧게, 상세는 이슈·MR 본문에 둔다. 보고서와 이슈·MR 본문도 `yd-writer-kr` 로 쓴다.
    
    ```
    ## 문서 현행화 — <기준>..HEAD
    - 고친 것: <파일 N개> — 주장마다 `이전 → 이후 + 근거`("README 를 갱신했다" 같은 요약만 남기지 않는다)
    - 기록으로 둔 것: <파일·줄> — <이유>
    - 확인 필요: <줄> — <무엇을 확인해야 하는지>
    - 대조하지 못한 범위: <폴더·문서 종류> — <이유(접근 불가·근거 원천 없음·시간)>
    - 검증: find_stale_refs current <n>건(사유 명시), <검증기> 통과
    ```
    
    커밋·MR 은 레포 워크플로(이슈 → 브랜치 → PR/MR)로 올린다. 문서 현행화는 코드 변경과 같은 MR 에 넣는 것이
    원칙이다(코드를 바꾼 MR 이 문서도 같이 고친다). 이미 머지된 변경을 뒤따라 맞출 때만
    별도 이슈로 연다.
    
    ## 완료 조건
    
    - `find_stale_refs.py --removed-since <기준>` 의 `current` 가 0 이거나, 남은 줄마다 둔 이유가 보고서에 있다.
    - 고친 서술마다 근거 파일·명령 결과를 확인했다.
    - 시점 기록과 생성물은 직접 고치지 않았다.
    - 고친 문장과 보고서·이슈·MR 본문을 `yd-writer-kr` 로 정리했다.
    - 다국어·언어 오버레이 짝 파일이 같은 커밋에 들어 있다.
    - 레포의 문서 검증기(링크 체커 0 broken 포함)와, 함께 바뀐 스크립트의 테스트가 통과한다.
    - 보고서·MR 본문에 대조하지 못한 범위를 적었다(없으면 「없음」). 빠뜨린 폴더가 다음 드리프트가 된다.
    
    ## Learned warnings
    
    - (2026-10-24) agents-scaffold 의 `docs-sync` 와 doksam-skills 의 `yd-doc-sync` 를 하나로 합쳤다. 드리프트 추출(`find_stale_refs.py`)·현행/기록 분류는 yd-doc-sync, 주장 단위 대조·"미검증" 표기·다국어 짝 파일 동시 갱신·링크 체커 게이트는 docs-sync 에서 왔다 (agents-scaffold #78).
    - (2026-10-24) 낡은 서술을 **삭제**로 처리하면 "왜 없어졌는지" 추적이 끊긴다 — 실측 일자와 함께 "미검증"으로 남기는 편이 낫다.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.