templates 모듈 안내

전역 작업 규칙은 ../CLAUDE.md가 진본이다. 이 파일은 templates/ 안의 배포 seed와 workflow snippet을 고칠 때의 컴퍼스이며, 그 자체가 외부 활성 프로젝트의 공개 계약은 아니다.

소유 범위

• /init-dcness가 사용자 프로젝트로 복사할 수 있는 GitHub workflow snippet.
• /design 계열에서 사용하는 design variant board seed.
• 템플릿은 dcness self 안의 파일이지만, 내용은 사용자 프로젝트에서 실행되거나 편집될 수 있다.

먼저 볼 파일

• github-workflows/: git naming, PR body, doc path, doc sync, GitHub Project lifecycle workflow snippets와 플랫폼별 lint-build-test(lint-build-test/<platform>.yml). 설치는 ../harness/ci_workflows.py가 workflow가 실행하는 검사 스크립트와 함께 사용자 repo의 .github/ci-checks/로 복사한다.
• design-variants/boards/screen-states.html: generated screen-state board seed.
• design-variants/_lib/canvas.js와 design-variants/_lib/: board engine helper.
• design-variants/drafts/.gitkeep: draft directory seed 유지 파일.
• ../commands/init-dcness.md: workflow template 복사와 사용자 프로젝트 배포 흐름.
• ../tests/test_canvas_design_workflow.py, ../tests/test_doc_path_integrity.py, ../tests/test_index_map_aggregate.py: 주요 회귀 테스트.

의존 관계 (dependencies)

• ../harness/ci_workflows.py가 github-workflows/와 design-variants/_lib/의 파일 목록을 가지고 있다. 파일을 추가하거나 이름을 바꾸면 그 목록을 함께 고친다.
• scripts/design/의 생성 스크립트가 design-variants/_lib/의 엔진을 프로젝트 사본과 비교한다.
• ../tests/design_variants_browser_smoke.mjs가 design-variants/를 임시 프로젝트로 복사해 headless Chrome 으로 검사한다.
• 주의: 이미 seed 를 받은 프로젝트의 docs/design-variants/_lib/ 사본은 plug-in 업데이트로 바뀌지 않는다. 엔진을 고치면 기존 프로젝트가 사본을 갱신하는 방법을 PR 본문에 적는다.

자주 하는 수정 (common change patterns)

• workflow template 을 추가하거나 고친다.
  1. github-workflows/의 파일을 고친다.
  2. 새 template 이면 ../harness/ci_workflows.py의 CHECKS에 등록하고 ../docs/plugin/init-dcness.md의 목록에 추가한다.
  3. python3.11 -m unittest tests.test_ci_workflows_install -v < /dev/null을 실행한다.
  4. 기존 프로젝트는 plug-in 업데이트 뒤 /init-dcness를 다시 실행해야 받는다. 이 내용을 PR 본문에 적는다.
• 디자인 보드 엔진(design-variants/_lib/)을 고친다.
  1. 엔진 파일을 고친다.
  2. PR 의 CI 에서 브라우저 smoke test 결과를 확인한다.
  3. 기존 프로젝트가 사본을 갱신하는 방법을 PR 본문에 적는다.

수정 시 주의점

• workflow template은 사용자 repo의 .github/workflows/로 복사된다. dcness self 전용 경로나 개인 환경 가정을 넣지 않는다.
• workflow가 호출하는 action/script 경로, checkout pin, repo owner 표기는 관련 테스트가 계약으로 본다.
• design variant seed는 사람이 바로 열어보고 편집하는 시작점이다. 생성된 draft 산출물과 seed 파일을 섞지 않는다.
• 새 template을 추가하면 /init-dcness copy step, 문서 inventory, 테스트 fixture 중 누락된 경로가 없는지 같이 확인한다.
• 외부 배포 영역에 내부 추적 ID나 dcness self만 아는 표현을 노출하지 않는다.

검증

# workflow template 변경
python3.11 -m unittest tests.test_ci_workflows_install tests.test_doc_path_integrity tests.test_index_map_aggregate -v < /dev/null
python3.11 -m unittest tests.test_canvas_design_workflow -v < /dev/null   # design variant 변경
node scripts/check_cross_refs.mjs                                         # 문서·링크 영향
python3.11 -m unittest discover -s tests -v < /dev/null                   # 범위가 섞이면 전체 suite