다중 표면 하니스 규약

다운스트림 기여자를 위한 정식 규범 참조. 이 문서는 프로젝트 명세의 다중 표면 하니스 규약 섹션(명세 §0.6 + §2.8 + §4.7)을 미러링하며, 게시된 저장소와 함께 배포되는 독립형 참조입니다. 아키텍처 근거는 ADR-0003에 기록되어 있습니다.

1. 왜 복수인가Copy Anchor Link

현대의 엔지니어링 표면에는 여러 하니스 — 채팅 콘솔, IDE 내 자동 완성 엔진, 페어 프로그래밍 도우미, 풀 리퀘스트 리뷰어 — 가 관여합니다. 각 하니스는 자체 정식 구성 파일을 읽습니다. 프로젝트가 이런 파일을 하나만 배포하면 나머지 런타임은 명시되지 않은 규약을 두고 조용히 제멋대로 동작하며, 누락된 저장소 내 메모리가 즉시 새어 나갑니다.

표면이 누락될 때 치르는 비용은 기계 생성 코드의 조용한 드리프트입니다 — 보이지 않게 누적되기 때문에 가장 나쁜 부류의 결함입니다. 기계가 생성하는 모든 아티팩트가 차이를 키우며, 사람 리뷰어가 모순을 발견할 즈음에는 코드베이스에 이미 몇 주 분량의 일관되지 않은 규약이 쌓여 있습니다.

하니스 런타임 구성은 배포 현실상 복수입니다. 게시되는 생태계는 §3의 세 가지 필수 표면을 배포해야 합니다(MUST). 세 표면은 AGENTS.md, 채팅 콘솔 런타임을 위한 행동 메모리 파일(CLAUDE.md), 그리고 IDE 내 자동 완성 런타임을 위한 저장소 범위 지침 파일입니다. 이 표면들은 서로 일관되어야 하며(MUST) — 모순도, 드리프트도 없이 — 같은 규율을 함께 담아야 합니다(MUST).

2. 일관성 계약Copy Anchor Link

범위 내(§3)의 모든 규약 표면은 프로젝트의 단일 규약 명세를 표현하는 채널입니다. 명세는 다음으로 나뉩니다.

• 공유 섹션 — 플랜 규율, 구조화된 질의(또는 표면에 상응하는 수단), 작성자 헤더, 명명, 안티패턴, 모달 계층. 이 섹션들은 모든 필수 표면에 나타나야 하며(MUST), 표면 간에 의미상 동등해야 합니다(MUST).
• 표면별 섹션 — 기능 프레이밍, 도구 호출 패턴, 코드 생성과 채팅의 차이. 이 섹션들은 표면마다 다를 수 있지만(MAY), 공유 섹션과 모순되어서는 안 됩니다(MUST NOT).

multi-surface-coherence 검증기(§7)는 모든 CI 실행과 pre-commit에서 실행되어 이 계약을 단언합니다.

이 표면들은 하나의 명세를 표현하는 서로 다른 채널입니다. 공유 섹션은 표면 간에 일치해야 합니다(MUST) — 의미상으로, 그리고 가능한 경우 어휘상으로도. 표면별 섹션은 공유 섹션과 모순되어서는 안 됩니다(MUST NOT).

3. 범위 내 표면Copy Anchor Link

이 저장소에서 옵트인 표면은 주장 목록 픽스처(tests/fixtures/multi-surface-claims.yaml)가 optional-in 아래에 나열하는 표면입니다. 사용하지 않는 벤더별 루트 구성은 의도적으로 두지 않습니다. 도구별 구성 파일은 해당 도구가 이 저장소의 활성 편집 표면일 때에만 추가됩니다.

4. IDE 내 지침 파일의 섹션 목록Copy Anchor Link

.github/ 아래의 저장소 범위 지침 파일은 다음 섹션을 이 순서대로 포함해야 합니다(MUST). 각 섹션은 아래의 정확한 헤딩 텍스트를 사용하며, 섹션 본문은 템플릿으로 찍어 내지 않고 직접 작성하지만 각 본문은 나열된 주장을 다루어야 합니다(MUST).

1. Project Context — 한 단락: 이 저장소가 무엇인지, 누가 사용하는지, 최상위 구조. 구체적으로 쓰며, 마케팅 문구는 넣지 않습니다.
2. Coding Conventions — 명명, 모달 계층, 프런트매터, Markdown 스타일, 기본값과 다른 경우의 언어별 스타일 사항.

3. File Headers — 런타임이 생성하는 모든 파일은 site/content/docs/reference/authorship-header.mdx에 따라 파일 타입에 맞는 주석 변형으로 작성된 정식 단일 SPDX-License-Identifier: MIT 줄로 시작해야 합니다(MUST). scripts/inject-header.*와 site/content/docs/reference/authorship-header.mdx를 가리킵니다.

4. Plans Discipline — 런타임은 하니스 구성 디렉터리(예: ~/.claude/plans/ 또는 ~/.codex/.plans/)나 그 밖의 전역 플랜 위치에 쓰는 코드나 스크립트를 생성해서는 안 됩니다(MUST NOT). 플랜 아티팩트는 site/content/docs/reference/plans-discipline.mdx에 따라 <project-root>/.apothem/plans/에 둡니다(레거시 <project-root>/.plans/ 트리는 apothem migrate-workspace로 업그레이드됩니다).
5. Structured Inquiry Behavior — 런타임은 불확실할 때 조용히 지어내서는 안 됩니다(MUST NOT). 대신 명확히 표시된 확인 요청 블록(예: # TODO(clarify): <question> 주석)을 삽입하고, 표면이 허용하는 경우 채팅에서 질문을 제기합니다. 지어낸 API, 지어낸 모델 이름, 지어낸 파일 경로는 금지합니다.
6. Forbidden Patterns — 명시적 금지 사항: 마케팅 형용사 금지, 얼버무리는 군더더기 표현 금지, console.log 디버그 잔재 금지, 사용자 홈으로의 하드코딩된 절대 경로 금지, 시크릿 커밋 금지, .apothem/plans/(또는 레거시 .plans/) 아래 파일 커밋 금지, 정식 프로젝트 지침 파일과의 모순 금지.
7. Output Format — 생성되는 코드/산문은 통합 대화형 출력 규약을 따릅니다: 단정성, 균일한 섹션 구성, 밀도, 요약 규율, 인용. 코드의 경우: 문서화된 공개 표면, 언어가 타입을 지원하는 경우 타입 지정, 테스트 스캐폴딩이 있는 경우 테스트.
8. Review Checklist — 리뷰어(사람 또는 PR 리뷰 모드의 런타임)가 승인 전에 확인해야 하는(MUST) 사항: 헤더 존재, 명명 규칙 준수, .apothem/plans/ 쓰기 없음, 정식 프로젝트 지침 파일과의 모순 없음, 로컬에서 검증기 녹색.
9. Pointers — AGENTS.md, CLAUDE.md, site/content/docs/reference/plans-discipline.mdx, site/content/docs/reference/authorship-header.mdx, 이 규약 문서, src/apothem/schemas/, CONTRIBUTING.md로의 링크.

이 파일은 site/content/docs/reference/authorship-header.mdx §2에 따라 정식 작성자 헤더 SPDX 줄(Markdown 변형)로 시작합니다 — 프로젝트가 선택한 헤더 가시성 정책에 따라 보이게 또는 보이지 않게 둡니다.

IDE 내 지침 파일은 AGENTS.md나 CLAUDE.md를 그대로 복사한 것이 아닙니다. AGENTS.md는 정식 프로젝트 지침 표면이고, CLAUDE.md는 이를 Claude Code용으로 미러링하며, IDE 내 지침 파일은 개발자가 수락하거나 거부하는 제안을 내보내는 편집기 내 코드 자동 완성 런타임에 맞는 어조로 작성됩니다. 정보(규율, 규약, 안티패턴)는 동일하고, 프레이밍이 다릅니다.

5. 주장 목록 참조Copy Anchor Link

tests/fixtures/multi-surface-claims.yaml의 픽스처는 각 공유 주장을 열거합니다. 샘플 항목:

- id: plans.location
  claim: "Planning artifacts live at <project-root>/.apothem/plans/, never inside a harness configuration directory."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
  optional-in: [site/content/docs/architecture/agents.mdx, .cursorrules]
- id: header.canonical
  claim: "Every applicable new file begins with the canonical SPDX-License-Identifier: MIT header line, in the comment family matching the filetype."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
- id: ambiguity.resolution
  claim: "Ambiguity is surfaced via the structured-inquiry channel or a clearly-marked TODO(clarify); never silently invented."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
# ... (one entry per shared claim)

검증기는 각 표면을 파싱하고, 각 주장이 표면에 존재하는지(헤딩 계층 + 본문 키워드 추출로) 찾으려 시도하며, 누락이나 모순이 하나라도 있으면 실패합니다.

6. 조정 규칙Copy Anchor Link

두 표면이 공유 주장에서 서로 모순되는 것으로 감지되면 기본 조정은 다음과 같습니다.

AGENTS.md는 정식 프로젝트 목소리입니다. 모순되는 표면은 AGENTS.md의 의미를 표면에 맞는 프레이밍으로 미러링하도록 다시 작성됩니다.

표면별 재정의는 의도적인 차이를 설명하는 ADR을 가리키는, 파일 내의 명시적 <!-- coherence-override: <claim-id> --> 마커가 있을 때에만 허용됩니다. 재정의 마커 자체도 검증기의 허용 목록에 열거되며 CI 보고서에 표시됩니다.

이 저장소에서 승인된 조정 전략은 **agents-md-wins**입니다. AGENTS.md가 정식이며, 활성화된 모든 하니스 미러는 의미상 동등하게 유지됩니다.

7. 검증기Copy Anchor Link

세 개의 검증기가 일관성 계약을 함께 구현합니다.

- in-IDE-instructions-presence    (src/apothem/conformity/copilot_instructions_presence_grep.py)
- multi-surface-coherence         (src/apothem/conformity/multi_surface_coherence_grep.py)
- license-author-consistency      (src/apothem/conformity/license_author_consistency_grep.py)

• 첫 번째는 IDE 내 지침 파일이 존재하고, 파싱되고, §4에 열거된 모든 정식 섹션을 포함하며, 정식 SPDX-License-Identifier: MIT 줄(Markdown 변형)로 시작함을 단언합니다.
• 두 번째는 각 표면의 정식 섹션을 파싱하고, 정규화된 비교기(대소문자 무시, 공백 차이 허용, 어휘적 바꿔 쓰기는 허용하되 픽스처에 정의된 주장 목록에 대해서는 의미상 동등성 요구)로 공유 섹션이 서로 일관됨을 단언합니다.
• 세 번째는 루트 LICENSE가 파싱 가능한 Copyright (c) <name> 줄을 담고 있음만을 단언합니다. 작성자 이름이 없는 파일별 헤더는 읽지 않습니다.

8. 표면 라이프사이클Copy Anchor Link

• 표면 추가. 운영자는 구조화된 질의 채널을 통해 옵트인합니다. 생성기는 주장 목록에 맞춰 표면을 작성하고, 검증기를 실행하며, 표면별 재정의가 필요하면 ADR을 제출합니다.
• 표면 제거. 구조화된 질의로 제거를 확인하고, ADR이 근거를 기록하며, 검증기의 required-in 목록을 수정합니다.
• 드리프트 감지. 주장 목록에서 벗어나는 커밋은 pre-commit / CI에서 거부되며, 커밋 작성자가 표면을 다시 작성해 일관성을 복원합니다.

함께 보기Copy Anchor Link

• ADR-0003 — 아키텍처 근거, 검토한 대안.
• tests/fixtures/multi-surface-claims.yaml — 정식 주장 목록 픽스처.
• AGENTS.md — 정식 프로젝트 목소리.
• CLAUDE.md — Claude Code 미러.
• site/content/docs/reference/plans-discipline.mdx — 플랜 규율 공유 주장의 정식 참조.
• site/content/docs/reference/authorship-header.mdx — 작성자 헤더 공유 주장의 정식 참조.
• 프로젝트 명세 §0.6 + §2.8 + §4.7 — 여기에 미러링된 전체 정식 텍스트.