멀티 서피스 하니스 규약

하위 기여자를 위한 정규 규범 참조. 이 문서는 프로젝트 명세의 멀티 서피스 하니스 규약 섹션(명세 §0.6 + §2.8 + §4.7)을 반영하며, 게시된 리포지터리와 함께 제공되는 독립형 참조입니다. 아키텍처적 근거는 ADR-0003에 기록되어 있습니다.

1. 왜 복수인가

현대의 엔지니어링 서피스는 여러 하니스 런타임——채팅 콘솔, IDE 내 자동 완성 엔진, 페어 프로그래밍 동반자, 풀 리퀘스트 리뷰어——에 의해 다루어집니다. 각 런타임은 자체 정규 구성 파일을 읽습니다. 프로젝트가 그러한 파일을 하나만 제공하면, 나머지 런타임은 선언되지 않은 규약에 대해 조용히 즉흥적으로 동작하며, 누락된 리포지터리 내 메모리가 즉시 새어 나갑니다.

서피스가 누락되는 비용은 기계 생성 코드의 조용한 드리프트입니다——눈에 보이지 않게 누적되기 때문에 최악의 결함입니다. 기계가 생성하는 모든 산출물이 분기를 가중시키며, 사람 리뷰어가 모순을 발견할 무렵에는 코드베이스가 이미 수 주 분량의 일관되지 않은 규약을 안고 있습니다.

코딩 런타임 구성은 배포 현실상 복수입니다. 게시된 생태계는 채팅 콘솔 런타임을 위한 동작 메모리 파일 그리고 IDE 내 자동 완성 런타임을 위한 리포지터리 범위 지시 파일을 제공해야 합니다(MUST). 두 서피스는 서로 일관되어야 하며(MUST)——모순도 드리프트도 없이——동일한 규율을 공동으로 인코딩해야 합니다(MUST).

2. 일관성 계약

범위 내(§3)의 모든 규약 서피스는 프로젝트의 단일 규약 명세를 표현하는 채널입니다. 명세는 다음으로 분해됩니다.

• 공유 섹션 — 플랜 규율, 구조화 질의(또는 서피스 등가물), 작성자 헤더, 명명, 안티패턴, 모달 계층. 이들은 모든 필수 서피스에 나타나야 하며(MUST), 서피스 전반에서 의미적으로 등가여야 합니다(MUST).
• 서피스 고유 섹션 — 역량 프레이밍, 도구 호출 패턴, 코드 생성과 채팅의 차이. 이들은 서피스마다 다를 수 있으나(MAY), 공유 섹션과 모순되어서는 안 됩니다(MUST NOT).

multi-surface-coherence 검증기(§7)는 모든 CI 실행 시 및 프리커밋 시 실행되어 계약을 단언합니다.

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

3. 범위 내 서피스

이번 작업에서 운영자는 픽스처가 기록한 선택적 어시스턴트 서피스를 옵트인했습니다. 사용되지 않는 벤더 고유 루트 구성은 의도적으로 부재합니다. 도구 고유 구성 파일은 해당 도구가 이 리포지터리의 능동적 편집 서피스인 경우에만 추가됩니다.

4. IDE 내 지시 파일의 섹션 목록

.github/ 아래의 리포지터리 범위 지시 파일은 이 순서로 다음 섹션을 포함해야 합니다(MUST)(각 섹션은 아래의 정확한 제목 텍스트를 사용한다. 섹션 본문은 템플릿으로 찍어내지 않고 작성하되, 각 섹션은 나열된 주장을 다루어야 한다 MUST).

1. Project Context — 한 단락: 이 리포지터리가 무엇인지, 누가 사용하는지, 최상위 형태. 구체적으로; 마케팅은 금지.
2. Coding Conventions — 명명, 모달 계층, frontmatter, 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, 이 규약 문서, 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. 주장 목록 참조

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 authorship-header banner per site/content/docs/reference/authorship-header.mdx."
  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. 조정 규칙

두 서피스가 공유 주장에 대해 모순되는 것으로 감지되면, 기본 조정은 다음과 같습니다.

AGENTS.md는 정규 프로젝트 목소리입니다. 모순되는 서피스는 AGENTS.md의 의미론을 서피스에 적합한 프레이밍으로 반영하도록 재작성됩니다.

서피스 고유 재정의는, 의도적 분기를 설명하는 ADR을 가리키는 명시적이고 파일 내적인 마커 <!-- coherence-override: <claim-id> -->가 있는 경우에만 허용됩니다. 재정의 마커는 검증기의 허용 목록에 그 자체로 열거되며 CI 보고서에 노출됩니다.

이 리포지터리의 경우, 비준된 조정 전략은 **agents-md-wins**입니다: AGENTS.md가 정규이며, 모든 능동적 하니스 미러는 의미적으로 등가로 유지됩니다.

7. 검증기

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

- 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에 열거된 모든 정규 섹션을 포함하고, 정규 작성자 배너로 시작함을 단언합니다.
• 두 번째는 각 서피스의 정규 섹션을 파싱하여, 공유 섹션이 정규화된 비교기 아래에서 서로 일관됨을 단언합니다(대소문자 구분 없음, 공백에 관대, 어휘적 의역 허용, 단 픽스처가 정의한 주장 목록에서 의미적 등가 요구).
• 세 번째는 LICENSE의 저작권 행과 정규 배너의 "Copyright (c)" 행이 동일한 작성자를 명명함을 단언합니다.

8. 서피스 라이프사이클

• 서피스 추가. 운영자는 구조화 질의 채널을 통해, 또는 이후의 make surfaces-add <name>을 통해 옵트인합니다. 생성기는 주장 목록에 대해 서피스를 작성하고, 검증기를 실행하며, 서피스 고유 재정의가 필요하면 ADR을 등록합니다.
• 서피스 제거. 구조화 질의가 제거를 확인하고, ADR이 근거를 기록하며, 검증기의 required-in 목록이 수정됩니다.
• 드리프트 감지. 주장 목록에서 벗어나는 커밋은 프리커밋 / CI에 의해 거부됩니다. 커밋 작성자는 일관성을 복원하기 위해 서피스를 재작성합니다.

함께 보기

• 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 — 여기에 반영된 완전한 정규 텍스트.