docs: spec system overhaul — frontmatter + lint + AGENTS.md + EARS infra#8
Merged
docs: spec system overhaul — frontmatter + lint + AGENTS.md + EARS infra#8
Conversation
- Status 인라인 형식 → YAML frontmatter (status / ga | target / supersedes / superseded_by / last_updated) - Frozen 면제 조항 추가 (Living-policy schema migration: non-semantic 형식 갱신만 허용, 결정·인용 보존, 전체 spec 일괄) - verification/ 정책 약화 (큰 단위 작업 한정 — 작은 작업은 git log + PR description SSOT) - last_updated 자동화로 전환 (수기 갱신 절차 폐기) - 명명 규칙에 상대경로 implicit 표준 추가 (./ prefix 금지) - Implementation log 구조에 meta-level slot 추가 (vX.Y.Z 외부 직속 평면, ga 생략 가능) - 신규 섹션: EARS 인수조건 (v0.4.0+) / CHANGELOG ↔ log 분리 / Frozen 외부 의존성 부패 / Trace report 후속 commit 들이 본 정책 따름. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
AGENTS.md 가 2025-12 Linux Foundation/AAIF 표준이 되어 Codex / Factory / Cursor / Kilo 등이 인식. 본문은 AGENTS.md 가 SSOT, CLAUDE.md 는 1줄 stub 으로 backward compat 유지. symlink 가 아닌 별도 파일 — Windows / 일부 git 클라이언트 호환성 우선. 기존 CLAUDE.md 본문 그대로 복사 + 다음만 적응: - frontmatter schema 반영 (Status inline → YAML) - /new-spec skill 언급 추가 (Documentation 섹션) - upstream-pins.yaml SSOT 언급 추가 (Versioning 섹션) - "AGENTS.md / CLAUDE.md" 둘 다 Living 명시 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
inline **Status**: 라인 → YAML frontmatter. 본문 의미 변경 0. Living-policy schema migration — Frozen 19개 / Draft 2개 / Active 3개 일괄 (CONVENTIONS § Frozen 면제 조항 — non-semantic 형식 갱신). 각 파일의 기존 메타 값 정확 보존: - ga / target / last_updated 모두 inline 값 그대로 frontmatter 로 이전 - v0.1.0/rhwp-python.md 의 "(patch v0.1.1)" annotation 만 drop (strict SemVer schema, README 인덱스 + CHANGELOG 가 v0.1.1 별도 노출) 부수 변경 2건: - .claude/hooks/docs-lint.py 의 rule #1 (Status header) 을 inline OR frontmatter 둘 다 허용으로 임시 확장 — Commit 4 에서 frontmatter-only 로 strict 화 + 새 룰 (schema / kebab-case / supersede chain) 추가 - docs/implementation/v0.3.0/aparse-cleanup.md 의 사전 존재 broken link (../../../upstream/... → ../../upstream/...) 수정 — Frozen 본문이지만 CONVENTIONS § Frozen 정의가 broken link in-place fix 명시 허용 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…rozen 옵션 A (Paragraph::control_text_positions 메서드 캡슐화) 가 우리 spec 그대로 edwardkim/rhwp#390 에 채택, 2026-04-28 PR #405 cherry-pick → devel 머지. 3 commits: 2a69fe1 / b855e2a / a59ce71. 상류 main 미반영 — 다음 external/rhwp pin bump 시 흡수 예정. 처리 방식: - 본 파일 in-place Frozen 전환 (status: Active → Frozen, ga 생략) - 본문 첫 헤더 위에 RESOLVED notice 한 줄 인용 블록 (PR/commit reference) - 기존 body 보존 — 다른 v0.3.0 Frozen spec (stage-2/3/4, aparse-cleanup) 이 본 파일 참조하므로 삭제 대신 보존 (link 유지, historical record) CONVENTIONS § upstream/ 정책 보강 — "해결 시" 두 옵션 (삭제 / in-place Frozen 전환) 명시. 기준: 다른 spec 의 참조 유무. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
변경사항: - CLAUDE.md stub 텍스트 삭제 - CLAUDE.md 를 AGENTS.md 심볼릭 링크로 교체 - 단일 소스 보장 — Claude Code 자동 로드 시 AGENTS.md 본문이 그대로 적용됨 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
기존 .claude/hooks/docs-lint.py 의 4개 룰을 scripts/_doc_lint.py 공통 lib 로 분리. CLI entry (scripts/lint_docs.py) 신설 — CI 에서 전체 repo scan. hook 은 편집 파일 단위 즉시 알림 유지. 추가 룰 (4 → 8): - frontmatter schema (status enum / ga ↔ target mutex / SemVer / 면제) - kebab-case 파일명 (README / CONVENTIONS 등 ALL-CAPS 예외) - vX.Y.Z 디렉토리 SemVer - <topic>.md ↔ <topic>-research.md pair 존재 - supersede chain integrity (양방향 참조 검증) Frontmatter ga 면제 (Frozen 한정): - meta-level docs/implementation/<topic>.md (vX.Y.Z 외부) - 해결된 docs/upstream/<topic>.md (특정 버전 미귀속) Pair grandfather: - v0.1.0 (spinoff transfer, 디자인 리서치 미진행) — pair 검사 면제 - v0.2.0/ir / v0.3.0/cli 의 -design-research suffix 수용 (legacy) - CONVENTIONS § 명명 규칙 에 grandfather 명시 + 신규는 -research.md 만 pyyaml 의존성 미추가 — flat string key:value 만 쓰는 frontmatter 라 hand-rolled parser 가 충분 + hook 은 system python3 라 venv 미접근 회피. CI: .github/workflows/docs.yml 신설 (paths filter 로 빌드/테스트와 분리, .md 또는 lint 스크립트 변경 시만 트리거). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
변경사항: - 글로벌 룰 적용 안내 섹션(헤더 + 본문) 삭제 — 3번 줄 한 줄 안내와 중복 - AI/사람 모두에게 자명한 메타 안내라 가치 낮음 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
전역 CLAUDE.md 의 "Use Typer instead of argparse" 정책 적용. typer 는 이미 [dependency-groups] testing 에 포함 → 추가 의존성 없음. --help 자동 + 타입 검증 + 프로젝트 다른 CLI (rhwp-py) 와 일관 UX. CI: docs.yml 가 setup-python 직접 호출 → setup-uv + typer 단발 install 로 전환. 가볍게 유지 (full all group 안 함). hook (.claude/hooks/docs-lint.py) 영향 0 — _doc_lint.py 만 import 하여 typer 미사용, system python3 호환 유지. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Frozen 면제 조항 (Living-policy schema migration) 의 일관 적용. Commit 3
에서 frontmatter 마이그를 non-semantic 으로 처리한 동일 논리 — 결정 / 인용 /
본문 의미 보존하고 표현 형식 (파일명 / 메타 형식) 만 정합화.
Rename (git mv, history 보존):
- docs/design/v0.2.0/ir-design-research.md → ir-research.md
- docs/design/v0.3.0/cli-design-research.md → cli-research.md
Cross-link 정정 (15개 파일, 24개 reference):
- roadmap/README.md, v0.2.0/ir.md, v0.3.0/cli.md, v0.3.0/ir-expansion.md
- design/v0.3.0/cli-research.md, ir-expansion-research.md
- implementation/v0.2.0/stages/stage-{1,2,3,4,5}.md
- implementation/v0.3.0/stages/stage-4.md
- CHANGELOG.md ([Unreleased] / [0.2.0] / [0.3.0] entry)
Lint 정리 (Commit 4 의 transitional grandfather 철회):
- _doc_lint.py 의 -design-research suffix 수용 로직 제거
- CONVENTIONS.md § 명명 규칙 의 grandfather 한 줄 제거
- 이제 단일 표준: <topic>.md ↔ <topic>-research.md (예외 0)
v0.1.0 페어 면제 (PAIR_EXEMPT_VERSIONS) 만 유지 — 진짜 historical
(spinoff transfer, 디자인 리서치 미진행) 케이스라 형식 통일 무관.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
external/rhwp 커밋 핀의 SSOT 를 yaml 로 분리. CHANGELOG.md 가 본 파일 값을 prose 로 인용 — 둘이 어긋나면 yaml 이 SSOT. scripts/update_upstream_pin.py — 릴리스 직전 작업자가 호출: - external/rhwp HEAD 의 short hash 추출 - 직전 entry 와 비교하여 commits_integrated 자동 계산 - 표준 field 순서 (upstream_commit / previous_commit / commits_integrated / bumped_at / note) 로 갱신, round-trip 안정 자동화 (release workflow 통합) 미적용 — 핀 결정은 "어느 commit 까지 흡수 할지" 사람의 판단이라 수기 한 단계 둠. typer + pyyaml. 초기 entries 4종 (v0.1.0 / v0.1.1 / v0.2.0 / v0.3.0) 채움: - v0.1.0 / v0.1.1: 1636213 (CHANGELOG + spec 본문 교차 검증) - v0.2.0: bea635b - v0.3.0: 033617e (380 commits from bea635b) pyyaml 을 [dependency-groups] dev 에 명시 — 기존 transitive 의존성을 SSOT 화. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
v0.4.0+ 신규 spec 의 인수조건 ↔ 테스트 매핑 자동화 인프라. 추가: - pyproject.toml [tool.pytest.ini_options] markers 에 spec(spec_id) 등록 - scripts/generate_spec_trace.py — AST 정적 분석으로 @pytest.mark.spec 데코레이터 추출 (subprocess 없이, typer + ast). --check flag 로 CI 검증 - docs/traces/coverage.md (Living, placeholder) — v0.4.0+ 첫 marker 시 자동 채워짐 - .github/workflows/docs.yml 에 trace --check step 추가 (paths 에 tests/ 포함 — marker 변경 시 트리거) 기존 v0.1.0 ~ v0.3.0 Frozen spec 은 AC ID 부여 안 함 — marker 없는 테스트 그대로 통과 (CONVENTIONS § Trace report). 검증: 합성 marker 3개 (v0.4.0/cli#AC-1 외) 로 추출 / 테이블 생성 round-trip 확인 후 cleanup. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
호출: /new-spec <version> <topic> (예: /new-spec v0.4.0 view-renderer) 산출: - docs/roadmap/<version>/<topic>.md (frontmatter Draft + EARS placeholder) - docs/design/<version>/<topic>-research.md (페어 ADR) - docs/roadmap/README.md 의 활성 spec 인덱스 row 추가 - 작업 후 scripts/lint_docs.py docs/ 자동 실행 (무결성 검증) CONVENTIONS § 새 spec 추가 절차 자동화. disable-model-invocation: true — 사용자 명시 호출만 받음. 콘텐츠 결정 (실제 결정 / 인수조건 / 비목표) 은 사람의 판단으로 유지, skill 은 구조 일관성만 자동화. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Edit / Write / MultiEdit 시 docs/*.md 의 frontmatter last_updated 를 오늘 날짜로 in-place 갱신. CONVENTIONS § Status 메타데이터 의 자동화 정책 구현 — 수기 갱신 절차 폐기. skip 조건: - docs/ 외부 파일 - frontmatter 없는 파일 (Living: CONVENTIONS / roadmap/README / traces/coverage) - last_updated 가 이미 오늘 날짜 - status 가 Frozen 또는 Superseded — 본문 의미 변경 금지가 원칙. 면제 조항 활용 일괄 마이그 vs 오타·링크 fix 둘 다 가능 → 자동 처리는 위험, 사용자가 명시 결정 settings.json 의 PostToolUse hook 배열에 등록 — docs-lint 보다 먼저 실행되어 lint 가 갱신된 frontmatter 를 검증. 검증: 합성 Draft 파일 (last_updated: 2026-01-01) → 오늘 날짜로 갱신, 합성 Frozen 파일은 그대로 유지. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
CHANGELOG.md [Unreleased] § Changed — 문서 시스템 대규모 개편 entry 작성. 사용자 facing API / wheel 영향 0 명시. 본 PR 의 8 변경 카테고리 + 부수 정리 (rename / 상류 #390) 모두 한 entry 로 압축. OVERHAUL_PLAN.md (루트) → docs/implementation/spec-system-overhaul.md (Frozen, vX.Y.Z 외부 직속 평면 — meta-level / cross-version 슬롯 활용, ga 필드 생략). 14개 결정 + 9 commit 단계 + a/b/c 옵션 비교 + invariant 정의 historical record 보존. PR 진행 중 발생한 사후 결정 (rename, RESOLVED in-place Frozen, typer 전환 등) 은 본 문서가 아닌 git log + commit message + CHANGELOG 가 보유 — frontmatter notice 로 명시. Cross-link 경로 보정 24건 (root → docs/implementation/ 이동에 따른 ../<...> / ../../<...> 변환): docs/* → ../*, CLAUDE/AGENTS → ../../ Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Ubuntu 24.04 의 system Python 이 externally-managed (PEP 668) 라 'uv pip install --system "typer>=0.12"' 가 거부됨 (exit 2). 해결: 'uv run --with "typer>=0.12" python ...' 로 ad-hoc 설치 — uv 가 임시 venv 자동 생성, lint 단발 호출이라 캐시 부담도 없음. 이전 commit baafe82 의 docs.yml 만 영향. ci.yml (build/test) 는 무관. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
이전 fix (uv run --with) 가 PEP 668 은 회피했으나 uv 가 pyproject.toml 의 [project] 를 보고 자동으로 maturin build_editable 을 시도. external/ rhwp submodule 미체크아웃 + Rust toolchain 미설치 → exit 1. 해결: --no-project 추가 → uv 가 pyproject 무시, 임시 venv 에 typer 만 설치. lint script 는 rhwp import 안 하므로 프로젝트 빌드 불필요. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
CI 의 docs.yml 이 external/rhwp submodule 체크아웃 안 해도 lint 통과 가능. 외부 의존성 (submodule 안 파일) 추적은 본 lint 의 책임 밖 — docs/upstream-pins.yaml 이 SSOT. 방식: validate_broken_link 가 link 의 resolved path 가 repo/external/ 하위면 skip. repo 외부 절대경로 (relative_to 실패) 도 skip. 영향 케이스: docs/design/v0.2.0/ir-research.md L105 의 "../../../external/rhwp/CLAUDE.md" 참조 (rhwp 코어의 waterfall 워크플로우 설명 link). Frozen body 라 link 제거 대신 lint 측 수용. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
검증 에이전트 보고 7건 모두 재검증 후 CONFIRMED → 적용.
scripts/_doc_lint.py:
- Major: validate_broken_link / validate_cross_link 의 code-fence false
positive — _strip_code() helper 추가 (```...``` + 인라인 백틱 제거).
본 fix 없이는 향후 spec 의 예시 link 가 violation 으로 오인식
- Minor: parse_frontmatter 가 trailing inline comment ('foo: bar # x')
를 value 로 흡수 → quote 시작 아닌 경우 ' #' 로 split
- Minor: _validate_supersede_chain 의 path depth 가정 (vX.Y.Z 2-level
하드코딩) → _supersede_base() 도입, meta-level 1-level 평면도 지원
scripts/generate_spec_trace.py:
- Minor: ast.walk 가 class 컨텍스트 평탄화 → class TestFoo: def test_bar
의 nodeid 가 ::test_bar 만 출력. _SpecMarkerVisitor (NodeVisitor +
class_stack) 로 정확히 ::TestFoo::test_bar 출력
scripts/update_upstream_pin.py:
- Minor: _previous_pin 의 SemVer 매치 실패 시 (0,0,0) silent fallback
(전역 fail-fast 정책 위반) → ValueError raise
.github/workflows/docs.yml:
- Minor: paths 의 '**.md' 가 lint 무관 .md (README/CHANGELOG/PR template
등) 변경에도 fire — 'docs/**' 가 이미 docs 하위 .md 포괄하므로 제거
.gitignore:
- .claude/scheduled_tasks.lock 추가 — ScheduleWakeup hook 의 PID/세션ID
lock 파일 (런타임 머신-로컬, repo 추적 무의미)
검증: 합성 케이스 4종 (fence false positive / class method / 잘못된
pin key / meta-level supersede) 모두 expected behavior. 기존 lint 0
violation 유지.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
전역 CLAUDE.md 정책: "Respond in Korean, except for code, technical terms, and LLM-facing text (CLAUDE.md, prompts, rules → English)". SKILL.md 는 Claude Code 가 /new-spec 호출 시 읽고 행동하는 prompt/rule 이라 영문이 정합. 변경: - procedure / rules / limits 섹션 prose: 영문화 - 템플릿 안의 한국어 placeholder hint (<...>): 영문 directive 로 (Claude 에 대한 지시이므로) - 템플릿 안의 *한국어 섹션 헤더* (## 결정 사항 / ## 인수조건 / 영구 비목표 등): 그대로 유지 — 생성된 문서가 한국어로 작성되어야 하므로 출력 형식의 일부 Lint 호출도 실제 동작하는 명령으로 갱신 (uv run --no-project --with). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
기존 25줄 setup-only → 60줄 path-based onboarding 가이드.
핵심 추가:
- TL;DR quick start (4 commands) — 30초 안에 빌드/테스트 가능 여부 확인
- "Pick your contribution path" 표 — 5가지 기여 유형별 (버그픽스 / 기능 /
Rust 코어 / 문서 / 새 spec) "추가로 읽을 문서 + 주의점" 매트릭스
- 90%+ PR (버그픽스) 은 본 문서 외 추가 reading 0 명시 — spec 시스템
정책 부담 회피
- 새 spec 작성 path 에서 /new-spec skill + CONVENTIONS § 새 spec 추가 절차 안내
- pre-submit checklist 에 docs/ lint 명령 추가
- 브랜치 네이밍 (PATCH vs MINOR) + Conventional Commits + PR 템플릿 명시
- "Where to learn more" 섹션 — AGENTS.md / CONVENTIONS.md / roadmap README /
upstream-pins.yaml 4개 링크
이전: setup 명령만, 어떤 PR 이 어떤 정책 알아야 하는지 가이드 0
이후: path-based — 외부 기여자가 자기 case 빠르게 식별 가능
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
기존 README.md / README_EN.md 와 동일한 i18n 패턴 적용: - CONTRIBUTING.md → 한글 primary (헤더에 'English' link) - CONTRIBUTING_EN.md → 영문 (헤더에 '한국어' link), git mv 로 history 보존 링크 정정: - README_EN.md 에 CONTRIBUTING_EN.md 참조 추가 (기존 누락) - AGENTS.md 의 contributor flow 링크 → CONTRIBUTING_EN.md primary (한글 link 도 보조로 명시) - README.md 의 한글 CONTRIBUTING.md 참조는 그대로 (이미 정확) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
본 PR 진행 중 도입했던 yaml SSOT 가 사실상 중복 — 같은 정보가 (a) git
submodule 자체 ('git ls-tree <tag> external/rhwp'), (b) CHANGELOG 산문
노트, (c) yaml 3 곳에 존재. 자동화 의도 (release notes 생성 등) 가 있긴
하나, 정작 yaml 을 *읽는* consumer 가 0개 — 쓰기만 하고 읽는 데 없음.
YAGNI 적용: 자동화가 실재할 때 그 시점에 *실제 필요한 형태* 로 도입이
정확. 미리 만들면 (1) stale 위험 (매 릴리스마다 수기 갱신 부담), (2) 3
SSOT 충돌 시 우선순위 미정의, (3) 미래 자동화가 원하는 schema 와 안 맞을
가능성.
삭제 대상:
- docs/upstream-pins.yaml
- scripts/update_upstream_pin.py
- pyproject.toml [dependency-groups] dev 의 pyyaml (sole consumer)
- uv.lock 갱신
문서 정리:
- docs/CONVENTIONS.md: § 디렉토리별 정책 의 tree 다이어그램에서 한 줄 제거
- AGENTS.md (= CLAUDE.md symlink): "SSOT: docs/upstream-pins.yaml" →
"git ls-tree <tag> external/rhwp" 로 정정
- CONTRIBUTING.md / CONTRIBUTING_EN.md: '더 읽을 자료' 섹션의 yaml link →
git submodule + CHANGELOG 안내로 변경
- CHANGELOG.md [Unreleased]: 본 entry 한 줄 제거
docs/implementation/spec-system-overhaul.md (Frozen) 의 D14 / Commit 5
섹션은 변경 없음 — historical record. 본 commit message + git log 가
"D14 를 도입했다가 YAGNI 로 철회" 의 SSOT.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EARS 5 패턴 강제는 본 프로젝트 규모 (월 1회 spec, Python binding) 에 과
ceremony — 가치 (모호성 감소) 대비 비용 (패턴 선택 + 키워드) 큼. 핵심
이득 (AC-N ID 로 trace 매핑) 만 유지하고 EARS 는 optional reference 로
완화.
CONVENTIONS.md § 인수조건 형식:
- "EARS 5 패턴 으로 작성한다" → "AC-N ID 부여, 형식은 자유 (testable +
명확하면 OK), EARS 패턴 참고 가능 (강제 X)"
- 기존 v0.1.0 ~ v0.3.0 spec 도 trace 는 매핑됨 (spec 단위, AC-N 생략)
CONVENTIONS.md § Trace report:
- v0.4.0+ → "vX.Y.Z/topic#AC-N" (full)
- v0.1.0~v0.3.0 → "vX.Y.Z/topic" (soft, AC 생략) — 일관성 확보
- 파일 단위: 'pytestmark = pytest.mark.spec("...")' 한 줄
SKILL.md placeholder: 5 패턴 list → 단순 "AC-N: <testable statement>",
EARS 는 optional reference 로 1줄 주석.
scripts/generate_spec_trace.py:
- _SpecMarkerVisitor 에 visit_Module 추가 — module-level pytestmark =
pytest.mark.spec(...) (단일 또는 list) 도 추출. 모든 test_* 함수에 자동
적용 (per-file mapping 지원, soft retrofit 핵심)
tests/ soft retrofit (26 파일):
- 매핑: test_smoke/parse/text_extraction/errors/svg_rendering/pdf_rendering/
async/from_bytes → v0.1.0/rhwp-python
- test_langchain_loader{,_ir}/test_ir_{schema,roundtrip,tables,iter_blocks,
schema_export,mapper,plain_text} → v0.2.0/ir
- test_ir_{picture,furniture,formula,footnote,list,caption,toc,field} →
v0.3.0/ir-expansion
- test_cli → v0.3.0/cli
- 기존 pytestmark 보유 파일 (slow / langchain) 은 list 형태로 추가
- 모든 파일에 file-level pytestmark + 한 줄 주석 (soft retrofit 표시)
검증:
- coverage.md: 4 spec / 384 test mapping (parametrize invocation 제외한
test 함수 단위)
- lint 0 violation, pytest 450 pass / 2 skip (regression 0)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
phase 추상화 폐기 — vX.Y.Z 디렉토리 자체가 작업 단위라 phase 라는 추가 묶음 layer 잉여. CONVENTIONS 의 phase 관련 항목 정리: - Active 정의 / 예시 (phase-N.md → upstream/<topic>.md) - 디렉토리 구조 다이어그램의 phase 라인 제거 - roadmap/ 정의의 phase-N.md 항목 제거 - Cross-link "또는 phase-N.md" 제거 - 새 spec 추가 절차의 phase 항목 제거 - "## Phase 완료 후" 섹션 통째 제거 Active 카테고리 자체는 upstream/ 가 남아 유지. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
phase 본문 (view 렌더러 / RAG 통합 / writeback 계획) 을 roadmap/README.md § 미착수 작업 계획 으로 흡수. minor 별 분해 (v0.4 view, v0.5 LlamaIndex, v0.6 Haystack / v0.8~v1.0 writeback) 보존. phase-N.md 두 파일 삭제. 근거: vX.Y.Z 디렉토리가 작업 단위라 phase 라는 별도 묶음 추상화 잉여. README 한 자리에 활성 spec + 미착수 계획 모두 노출. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
phase 폐기로 broken 된 link 정리: - spec-system-overhaul.md L74 (Active 예시 표) - v0.1.0/rhwp-python.md L71 (§ 범위 외) Frozen body 변경 — CONVENTIONS L12 "오타·링크 수정만 in-place 허용" 적용. link 만 제거하고 텍스트 보존 (historical record 유지), 현재 위치는 README redirect. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ci.yml / docs.yml 의 기존 패턴 (PR 만 cancel, main push 는 보존) 을 일관 적용. 새 push 마다 이전 PR run 자동 cancel — 자원 절약 + PR Commits 탭 시각 노이즈 정리. publish.yml / publish-schema.yml 은 cancel-in-progress: false 유지 (partial publish / Pages race 방지). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
paths-ignore 가 required check "All tests passed" 와 충돌 — docs-only commit 시 workflow skip → status 가 expected 에서 stuck. GitHub 공식 docs 도 권고하는 changes job + job-level if 패턴으로 전환. 변경사항: - paths-ignore 제거 — workflow 자체는 항상 트리거 - changes job 신규 (dorny/paths-filter v4, predicate-quantifier: every) - 모든 test job 에 needs/if 추가 — docs-only commit 은 if-skip (success) - all-tests-passed 의 alls-green 에 allowed-skips 명시 - codeql.yml analyze: schedule || code change 조건 (cron 항상 분석) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
disable-model-invocation: true 제거 → Claude / 외부 AI agent (Codex /
Cursor) 가 자연어 의도 ("v0.4.0 view 렌더러 시작") 에서 자동 호출 가능.
description 필드에 invocation trigger 예시 + idempotent / pre-confirm
규약 명시 — model 이 의도 매칭 + 사용자 사전 확인 패턴 자연스럽게 따름.
안전장치 (skill 자체):
- 기존 spec 파일 있으면 abort (덮어쓰기 X)
- 출력 bounded: 3 파일 + README 1 행
- non-destructive: 신규 파일 / 인덱스 추가만
- lint 즉시 검증
오용 위험은 "Claude 가 호출 전 의도 명시 + 사용자 확인" 컨벤션으로 회피.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
본 PR 은 단일 PR 로 14개 결정 일괄 적용하는 문서 운영 체계 정비. 사용자 facing API / wheel 영향 0.
**Status**: ...라인 → YAML frontmatter 로 전면 마이그 (24개 spec — Frozen 19 / Draft 2 / Active 3). CONVENTIONS § Frozen 면제 조항 (Living-policy schema migration: non-semantic 일괄 마이그 in-place 허용) 신설scripts/lint_docs.pytyper +scripts/_doc_lint.py공통 lib) — 8 룰 (frontmatter schema / supersede chain / kebab-case / 페어 / vX.Y.Z 디렉토리 / cross-link 방향성 / monorepo 잔재 / 깨진 링크)..claude/hooks/docs-lint.py가 같은 lib 재사용. CIdocs.ymlworkflow 분리pytest.mark.spec("vX.Y.Z/topic#AC-N")marker +scripts/generate_spec_trace.py(AST 정적 분석) →docs/traces/coverage.md(Living) 자동 매핑. v0.4.0+ 신규 spec 부터 적용/new-spec <version> <topic>Claude Code skill — 새 version spec + 페어 ADR + README 인덱스 row + EARS placeholder 일괄 생성docs/upstream-pins.yaml(Living) SSOT +scripts/update_upstream_pin.py(typer + pyyaml round-trip 안정) —external/rhwp커밋 핀 자동 추출last_updated자동 갱신 hook (.claude/hooks/update-last-updated.py, PostToolUse) — Frozen / Superseded / Living skip부수 정리:
edwardkim/rhwp#390(find_control_text_positions) 옵션 A 채택 → cherry-pick 머지 → 본 spec in-place Frozen 전환 + RESOLVED notice<topic>-design-research.md→<topic>-research.md명명 통일 (v0.2.0/ir, v0.3.0/cli rename + 24 cross-link 일괄 정정)Why
2026-04 시점 SDD (Spec-Driven Development) 트렌드 조사 결과 본 프로젝트의 "Spec-driven + immutable per-version" 디자인은 외부 도구 (Spec-Kit / Kiro / OpenSpec / BMAD) 대비 한 단계 깊으나, 집행 이 인간 검열 + LLM 협조에만 의존. frontmatter 표준화 + lint 자동화 + skill 스캐폴딩으로 같은 디자인을 자동 보장으로 격상.
Scope
pyyaml(dev only)Test plan
uv run python scripts/lint_docs.py docs/— 0 violations (24 spec frontmatter schema 일관)uv run pytest -m "not slow"— 450 pass / 2 skip (sample data limitation, pre-existing) / 0 failRelated
🤖 Generated with Claude Code