| name | docs-sync-after-edits |
| description | 코드를 바꾼 뒤 그 변경에 영향받은 문서를 찾아 README·API 레퍼런스·인라인 주석을 코드와 일치하게 맞추는 닫힌 루프입니다. 사용자가 "코드 바꿨으니 문서도 맞춰줘", "README랑 주석 코드에 맞게 업데이트", "변경된 부분 문서 동기화", "이번 diff에 맞춰 docs 갱신", "API 레퍼런스 최신화", "sync docs after edits", "update README to match the code", "docs sync after edits"처럼 코드 변경 이후 뒤처진 문서를 코드에 다시 맞추고 싶을 때 사용하세요. (구분: 출시 후 CHANGELOG 항목 채우기는 looping:changelog-sync-after-ship, API 응답이 OpenAPI/JSON Schema 계약과 맞는지 검증은 looping:api-contract-until-match, openapi.yaml 스펙 자체를 라우트와 동기화는 looping:openapi-sync-until-valid, 구현 후 코드 정리 패스는 looping:de-sloppify-pass) |
편집 후 문서 동기화 (Docs Sync After Edits)
코드를 바꾼 뒤 영향받은 문서를 찾아 README·API 레퍼런스·인라인 주석을 코드와 일치하게 맞춥니다.
| 항목 | 값 |
|---|
| 카테고리 | 유지보수(Maintenance) |
| 트리거 | 수동(manual) — 사람이 직접 시작 |
| 종료 조건(Exit) | 영향받은 문서가 전부 업데이트되고 diff와 대조해 검증되었을 때 |
| 반복 한도(Max iterations) | 3 |
| 매 반복 체크 명령 | git diff main...HEAD --name-only |
| 가드레일 | 강화됨(Hardened) |
| 지원 에이전트 | Cursor |
이 루프는 언제 쓰나
기능을 고치거나 API 시그니처·설정 옵션·동작을 바꾼 뒤, 문서가 슬그머니 뒤처질 때 씁니다. README의 예제는 더 이상 돌아가지 않고, API 레퍼런스는 옛 파라미터를 가리키고, 주석은 사라진 동작을 설명하는 식이죠. 이 루프는 코드를 정답으로 삼아 변경 diff를 읽고 → 영향받은 문서를 찾아 → 코드에 맞게 고치고 → diff와 대조해 검증하는 패스를 반복합니다. 핵심은 추측으로 문서를 새로 쓰는 게 아니라, 실제로 바뀐 부분만 정확히 짚어 문서를 코드에 다시 맞추는 것입니다.
루프 흐름
수동 시작 → 변경 영역 식별 → 오래된 문서 탐색 → 문서 업데이트 → 정확성 검증
↑ │
│ 〔피드백 게이트〕
│ 영향받은 문서 전부
└──────────────────────────────────────────────── 검증됨? │ 아니오
│ 예
종료
매 반복(pass)마다 하는 일
- 변경 영역 식별 — 현재 diff를 검토합니다. 바뀐 공개 API, 설정 옵션, 동작을 목록으로 정리합니다.
git diff main...HEAD --name-only
- 오래된 문서 탐색 — README,
docs/, 코드 주석에서 바뀐 동작을 언급하는 부분을 찾습니다. 뒤처진 섹션에 표시를 남깁니다.
- 문서 업데이트 — 문서를 코드에 맞게 고칩니다. 예제는 실제로 돌아가고 정확하게 유지하세요. 더 이상 유효하지 않은 섹션은 삭제합니다.
- 정확성 검증 — 업데이트한 문서를 diff와 다시 대조해 읽습니다. 모순이 남지 않았는지 확인합니다.
가드레일 (점수 조작 방지 규칙)
종료 조건을 "가짜로" 통과시키지 못하게 막는 규칙입니다. 반드시 지키세요.
- 체크 명령이나 종료 기준을 고쳐서 억지로 성공시키지 않는다.
- 체크를 건너뛰거나 비활성화·우회해서 종료 조건을 통과시키지 않는다.
- 여러 번 반복해도 막히면, 지표를 조작하지 말고 멈추고 블로커를 보고한다.
Claude Code에서 실행하기
가장 간단합니다. 아래 kickoff 프롬프트를 그대로 붙여넣으면 에이전트가 스스로 반복합니다.
"편집 후 문서 동기화(Docs Sync After Edits)" 루프를 시작합니다.
목표: 문서가 현재 코드 변경과 일치하게 한다
최대 반복: 3
매 반복 사이 실행: git diff main...HEAD --name-only
종료 조건: 영향받은 문서가 모두 업데이트되고 검증되었을 때
1단계: diff를 검토하고, 오래된 문서를 찾아 업데이트한 뒤, 정확성을 검증한다.
이 루프를 스스로 페이싱(self-pace)하라. 매 반복 후 체크 명령을 실행하고 출력을 읽어, 종료
조건이 충족되지 않았을 때만 계속한다. 종료 조건이 통과하거나 최대 반복에 도달하면 멈춘다.
매 회차마다 한 줄 상태 업데이트를 남긴다.
팁: git diff main...HEAD --name-only는 기본 브랜치가 main이고 PR 브랜치에서 작업할 때 기준입니다. 기본 브랜치가 다르면 git diff develop...HEAD --name-only처럼, 아직 커밋 전이면 git diff --name-only로 바꾸세요.
팁 / 변형
- 체크 명령 바꾸기: 스테이징한 변경만 보려면
git diff --cached --name-only, 마지막 커밋 범위만 보려면 git diff HEAD~1 --name-only로 좁히세요. 모노레포라면 -- packages/foo 처럼 경로를 덧붙여 영향 범위를 한 패키지로 한정할 수 있습니다.
- 막힐 때: 같은 섹션을 두 번 손봤는데도 코드와 모순이 남으면, 가드레일대로 추측으로 메우지 말고 멈춰서 "어느 동작이 정답인지" 사람에게 확인을 요청하게 하세요.
- 범위 좁히기: 우선
README와 공개 API 레퍼런스만 맞추고 싶다면 2단계 탐색을 그 파일들로 한정하세요. 인라인 주석은 별도 패스로 미뤄도 됩니다.
- 연관 루프: 출시 후 CHANGELOG 항목 채우기는
looping:changelog-sync-after-ship, API 응답이 계약과 맞는지 검증은 looping:api-contract-until-match, OpenAPI 스펙 자체 동기화는 looping:openapi-sync-until-valid.
원본 영어 kickoff (loops.elorm.xyz 원문)
Start the "Docs Sync After Edits" loop.
Goal: documentation matches the current code changes
Max iterations: 3
Between iterations run: git diff main...HEAD --name-only
Exit when: all affected docs are updated and verified
Step 1: Review the diff, find stale docs, update them, and verify accuracy.
Self-pace this loop. After each iteration, run the check command, read the output, and only continue if the exit condition is not met. Stop when the exit condition passes or max iterations is reached. Give a short status update each pass.
출처: https://loops.elorm.xyz/loops/docs-sync-after-edits
