계획 디시플린 — 프로젝트 로컬 임시 작업 메모리

다운스트림 기여자를 위한 정규 규범 참조. 이 문서는 프로젝트 명세의 계획 디시플린 섹션(Spec §3)을 미러링합니다. 게시된 저장소와 함께 배포되는 독립형 참조입니다. 여기서 도입하는 디시플린은 기초적이며, 아래의 모든 지시는 명시적으로 달리 표시되지 않는 한 MUST입니다. 아키텍처적 근거는 ADR-0001에 기록되어 있습니다.

1. 정의 및 경계Copy Anchor Link

계획이란 프로젝트에 대해 추론하는 동안 생성되는, 의도적이고 일시적인 작업 산출물을 말하며, 다음으로 한정되지 않습니다:

• 아키텍처 스케치, 시스템 설계 워크스루, 컴포넌트 분해.
• 작업 분해 구조, 다단계 작업 목록, 분해 트리.
• 리팩터링 전략, 마이그레이션 워크스루, 롤아웃 순서.
• 디버깅 일지, 가설 로그, 재현 노트.
• 탐색 노트, 스파이크 기록, 프롬프트 초안, 나중에 쓰기 위해 보관한 어시스턴트 대화 기록.
• 출시하기 위해서가 아니라 그것으로 생각하기 위해 쓰인 모든 문서.

계획은 다음 인접 클래스들과 범주적으로 구별됩니다:

계획은 ADR에 선행합니다. 계획이 지속적 결정으로 수렴하면, 그 결정은 ADR로 승격됩니다(§4 라이프사이클). 계획 자체는 아카이브되거나 폐기됩니다.

2. 위치, 가시성, 명명Copy Anchor Link

• 경로. <project-root>/.apothem/plans/가 유일한 정규 홈입니다. 레거시 <project-root>/.plans/ 트리는 더 이상 정규가 아닙니다. apothem migrate-workspace(§5)로 업그레이드하십시오. 하니스 구성 디렉터리(예: ~/.claude/plans/, ~/.claude/.plans/, ~/.codex/.plans/)가 아닙니다. 데스크톱 스크래치 폴더가 아닙니다. ~/notes/가 아닙니다. tmp/plans/가 아닙니다.
• 가시성. 이 폴더는 §6의 정규 스니펫에 따라 프로젝트의 .gitignore에 등록됩니다. 하니스는 어떤 쓰기 전에도 이 항목이 있는지 반드시 검증해야 합니다. 없으면 한 줄짜리 헤더 주석과 이 문서로의 링크와 함께 항목을 추가합니다.
• 파일명 규약. YYYY-MM-DD--<kebab-case-slug>.md. 더 큰 워크스페이스의 경우 .apothem/plans/<area>/YYYY-MM-DD--<slug>.md 아래에 하위 분류합니다.
  • 예: .apothem/plans/2026-04-30--auth-refactor-strategy.md, .apothem/plans/api/2026-04-30--rate-limit-rollout.md.
• 인덱스. 선택 사항인 .apothem/plans/INDEX.md(역시 gitignore 대상)는 링크와 상태를 집계할 수 있으며, 존재하는 경우 하니스가 계획을 쓸 때마다 이를 유지합니다.
• 아카이브. 수렴되었거나 포기된 계획은 .apothem/plans/_archive/로 옮깁니다. 명시적인 구조화된 질의 확인 없이는 결코 삭제되지 않습니다.
• 계획의 저작권 헤더. 계획은 저작권 헤더 SPDX 라인에서 면제됩니다(site/content/docs/reference/authorship-header.mdx의 §면제 목록 참조). 계획은 gitignore 대상의 일시적 산출물이며, 일시적 작업 메모리에 영구 출처 표지를 붙이는 것은 범주 오류입니다. 프런트매터(§3)가 계획의 출처를 담습니다.

3. 프런트매터 스키마(검증됨)Copy Anchor Link

모든 계획 파일은 다음을 담습니다:

---
title: <human-readable title>
project: <git-remote-url-or-canonical-local-path>
created: <ISO-8601 timestamp>
updated: <ISO-8601 timestamp>
status: draft | in-progress | converged | abandoned
tags: [<kebab>, ...]
supersedes: <prior-plan-relative-path or null>
promotes-to: <ADR path or null>
---

계획용 JSON 스키마는 src/apothem/schemas/plan.schema.json에 있습니다. /plan 슬래시 명령(및 plans-discipline-language 검증기)은 모든 쓰기 시 이 스키마에 대해 검증합니다.

4. 라이프사이클 및 승격 워크플로Copy Anchor Link

1. 초안 — 최초 생성; status: draft.
2. 진행 중 — 활발히 반복 작업 중; status: in-progress; 실질적인 편집마다 updated를 갱신합니다.
3. 수렴 — 지속적 결정이 결정화됨:
   1. 그 결정을 프로젝트가 비준한 ADR 위치에 새 ADR로 추출합니다.
   2. 계획의 promotes-to를 ADR 경로로 설정합니다.
   3. status: converged로 설정합니다.
   4. 선택적으로 .apothem/plans/_archive/로 옮깁니다.
4. 포기 — 방향이 포기됨; status: abandoned; 아카이브하거나, 명시적인 구조화된 질의와 함께 폐기합니다.
5. 대체 — 새 계획이 이전 계획을 대체할 때, 새 계획의 supersedes를 이전 계획의 경로로 설정하고 이전 계획의 status를 그에 맞게 설정합니다.

승격은 계획 내용이 지속적이고, 버전 관리되며, 팀원에게 보이게 되는 유일한 경로입니다. 어떤 계획도 커밋되는 소스로 통째로 마이그레이션되지 않습니다.

5. 마이그레이션 프로토콜 — 일회성, 하니스 계획 디렉터리에서 프로젝트별 .apothem/plans/로Copy Anchor Link

참고. 이 프로토콜은 계획 디시플린을 처음 채택하는 다운스트림 프로젝트에 적용되며, 이때 이전 계획 산출물은 하니스 구성 디렉터리(예: ~/.claude/plans/, ~/.claude/.plans/, 또는 다른 하니스의 동등한 경로) 안에 있습니다. 생태계 자체에 대한 재귀적 경우는 하니스 로컬 계획 상태를 소스로 물리적으로 옮기는 대신 gitignore 처리함으로써 해결됩니다.

도구. 이미 레거시 레이아웃을 사용하는 프로젝트(형제 <project-root>/.plans/ 트리와 하니스별 <project-root>/.apothem/<harness>/{memory,contexts,learning} 저장소)의 경우, apothem migrate-workspace 명령은 둘 모두를 공유 <project-root>/.apothem/{plans,memory,learning,contexts} 작업 디렉터리로 합칩니다. 이 명령은 멱등적이고 비파괴적입니다. 소비하는 모든 원본을 백업하고, .plans/를 .apothem/plans/로 옮기며, 하니스별 메모리와 컨텍스트 저장소를 합집합으로 병합하고, 학습 신호를 이어 붙인 뒤 중복을 제거하며, 충돌하는 레코드는 결코 덮어쓰지 않습니다. 먼저 이동 내용을 미리 보려면 apothem migrate-workspace --dry-run을 실행하십시오.

마이그레이션은 멱등이며, 하니스 로컬 계획 디렉터리가 제거되는 시점까지는 되돌릴 수 있습니다(그 이후에는 ./.audit/plans-backup-<timestamp>.tar.gz의 백업 tarball이 롤백 산출물이 됩니다). 아래 예시는 ~/.claude/plans/를 사용합니다. 활성 하니스의 동등한 경로로 대체하십시오.

1단계 — 인벤토리. 하니스 로컬 계획 디렉터리 아래의 모든 파일을 열거하여 plan-artifact (quarantined)로 분류합니다.

2단계 — 출처 맵. 각 계획에 대해, 프런트매터 project 필드, 본문 스캔 신호(저장소 URL, 패키지 이름, 절대 경로), 맥락적 단서에서 도출한 추정 대상 프로젝트와 신뢰도 점수를 담은 출처 기록을 구축합니다.

3단계 — 매핑 확인. 전체 맵을 운영자에게 하나의 통합된 구조화된 질의로 제시합니다(파일 수가 편안한 단일 프롬프트 크기를 넘으면 촘촘하게 묶은 시퀀스로). 각 계획에 대해 운영자는 다음 중에서 선택합니다:

• 확인(Confirm): 추정된 대상 프로젝트를 확인합니다.
• 재할당(Reassign): 다른 프로젝트로 재할당합니다(운영자가 알고 있는 프로젝트 목록을 제시하는 옵션).
• 연기(Defer): 나중에 분류하기 위해 ~/.claude/.audit/orphan-plans/<original-name>으로 옮깁니다.
• 폐기(Discard): 명시적이고 별도로 확인된 구조화된 질의가 있을 때만 가능합니다(이는 파괴적입니다).

신뢰도가 high인 계획이 많을 때, 프롬프트는 모든 개별 결정을 로그에 여전히 노출하면서 왕복을 줄이기 위한 confirm-all-high-confidence 어포던스를 제공합니다.

4단계 — 이동 전 프로젝트 준비. 각 고유한 대상 프로젝트에 대해:

1. 프로젝트 루트가 존재하고 읽을 수 있는지 검증합니다.
2. git 저장소인지 검증합니다(비-git 루트의 경우, 진행, 초기화, 건너뛰기 중 무엇을 할지 구조화된 질의 채널을 통해 노출합니다).
3. <project-root>/.apothem/plans/가 존재하는지 확인하고, 없으면 mkdir -p로 생성합니다.
4. 프로젝트의 .gitignore에 §6의 정규 스니펫이 들어 있는지 검증하고, 없으면 이 마이그레이션을 명시하는 헤더 주석과 함께 추가합니다.
5. <project-root>/.apothem/plans/가 이미 git에 의해 추적되고 있지 않은지 검증합니다. 추적되고 있다면(이전 기여자의 실수), untrack-and-keep, untrack-and-remove-from-history, abort 옵션과 함께 구조화된 질의 채널을 통해 노출합니다.

5단계 — 이동. 확인된 각 계획 → 대상 짝짓기에 대해:

1. 대상 파일명을 계산합니다. 원본에 프런트매터가 있으면 §3에 따라 정규화하고, 없으면 본문을 프런트매터(status draft, project 필드 설정, created는 mtime에서, tags [migrated])로 감싼 뒤 YYYY-MM-DD--<slug>.md로 이름을 바꿉니다.
2. 대상에 이름 충돌이 있으면 -imported-<unix-timestamp>를 덧붙이고 이름 변경을 로그에 남깁니다.
3. 파일을 복사(mtime 보존)하고, 대상에서 SHA-256이 일치하는지 검증한 다음 원본을 삭제(unlink)합니다.
4. <project-root>/.apothem/plans/_migration-manifest.md(역시 gitignore 대상)에 항목을 덧붙여, 원본 하니스 로컬 경로, 대상 경로, 원본 SHA-256, 타임스탬프, 이 이동을 승인한 구조화된 질의 응답을 기록합니다.

6단계 — 검증. 모든 이동이 끝난 뒤:

1. 하니스 로컬 계획 디렉터리가 비어 있는지 확인합니다(고아 계획이 있다면, 곧 삭제될 디렉터리 바깥의 그 하니스 감사/격리 디렉터리 안에 있습니다).
2. 각 대상 프로젝트에 내용이 채워진 .apothem/plans/와 매니페스트가 있는지 확인합니다.
3. 이동된 내용이 원본과 일치하는지 SHA-256으로 표본 검사합니다.

7단계 — Tarball 및 제거. 1단계에서 찍은 임시 스냅샷에서 추출한, 이동 이전의 하니스 로컬 계획 트리 전체를 담은 ./.audit/plans-backup-<ISO-timestamp>.tar.gz를 생성합니다. 그런 다음 준비 완료를 확인하는 최종 구조화된 질의를 거쳐, 이제 비어 있는 하니스 로컬 계획 디렉터리를 제거합니다.

8단계 — 감사 기록. 모든 이동, 모든 연기된 파일, 모든 폐기, 모든 충돌 이름 변경, 모든 gitignore 추가를 요약하는 ./.audit/plans-migration.md를 발행합니다.

6. 다운스트림 .gitignore 스니펫(정규, 복사-붙여넣기)Copy Anchor Link

이 생태계를 채택하는 모든 프로젝트는 자신의 .gitignore에 다음 블록을 반드시 추가해야 합니다:

# Apothem working directory (project-local shared state: plans, memory,
# learning, contexts; gitignored — never committed). The sole canonical plans
# home is `.apothem/plans/`.
# See: <repo-url>/blob/main/site/content/docs/reference/plans-discipline.mdx
# Ignore the CONTENTS of this directory (not the directory) so the
# `.keep` negation below can take effect.
.apothem/*
!.apothem/.keep

선택적인 .keep 면제는 내용을 누출하지 않으면서, 빈 경로를 정리하는 도구에서도 디렉터리가 존재하도록 보존합니다. .keep을 포함할지는 /plan을 처음 호출할 때 구조화된 질의 채널을 통해 프로젝트별로 결정됩니다. .apothem/* + !.apothem/.keep 라인이 정규 스니펫입니다. 여전히 레거시 <project-root>/.plans/ 트리를 가진 프로젝트는 apothem migrate-workspace(§5)를 실행하여 .apothem/plans/로 업그레이드하십시오.

7. 자기 강제 메커니즘Copy Anchor Link

이 디시플린은 앞으로의 모든 세션에서 살아남아야 합니다. 다음 강제 표면은 필수이며 게시된 생태계에 인코딩되어 있습니다:

1. AGENTS.md 및 미러 지시 표면 — 다음을 명시하는 최상위 필수 행동 블록: "계획 산출물은 <project-root>/.apothem/plans/에 작성됩니다. 유일한 정규 계획 홈입니다(레거시 <project-root>/.plans/ 트리는 apothem migrate-workspace를 통해 업그레이드됨). 어떤 하니스 구성 디렉터리(예: ~/.codex/ 또는 ~/.claude/)에도, 전역 위치에도 결코 작성하지 않습니다. 이 규칙은 협상할 수 없습니다. 관련된 모든 결정에서 프로젝트 명세의 §3을 인용하십시오." 이 블록은 plans-discipline-language 검증기가 감지합니다.
2. 하니스별 저장소 내 지시 파일 — 그 하니스의 지시 표면에 맞는 틀로 같은 지시를 미러링합니다(§4 Plans Discipline). 등록된 각 하니스 표면에서 같은 검증기가 감지합니다.
3. 기본 출력 스타일 — 응답이 계획 형태의 내용(다단계 전략, 분해, 설계 워크스루, 디버깅 일지)을 만들어 낼 때, 스타일은 그 산출물을 인라인으로 출력하고 버리는 대신 프로젝트 로컬 .apothem/plans/에 쓰도록 보냅니다. 스타일은 명시적으로 지시합니다: "프로젝트 루트를 찾을 수 없으면, 어디에 계획할지 운영자에게 묻는 구조화된 질의로 중단한다."
4. 모든 위임된 워커 프롬프트 — 계획 산출물의 대상으로 .apothem/plans/를 명시하는 Output Surface 조항과, 하니스 로컬 계획 디렉터리를 금지 대상으로 명시하는 Anti-Pattern 조항을 담습니다.
5. 전용 /plan 슬래시 명령 — slug와 본문을 받아 올바른 프런트매터로 <project-root>/.apothem/plans/YYYY-MM-DD--<slug>.md에 씁니다. 대상의 .gitignore가 올바른지 보장하며, 하니스 구성 루트 경로에 쓰는 것을 거부합니다.
6. pre-tool-use 훅 — plan-write-guard — 모든 파일 쓰기 도구 호출을 가로챕니다. 대상 경로가 하니스 로컬 계획 위치(예: ~/.claude/plans/... 또는 ~/.codex/.plans/...)이거나, 휴리스틱이 계획 형태로 식별하는 다른 전역 생태계 경로와 일치하면, 훅은 쓰기를 차단하고 현재 프로젝트의 .apothem/plans/로 방향을 바꾸도록 제안하는 구조화된 질의를 띄웁니다.
7. CI 검증기 — no-global-plans는 커밋된 계획 작업 메모리가 게시된 트리에 다시 나타나면 빌드를 실패시킵니다. plans-discipline-language는 정식 지시가 등록된 하니스 지시 파일이나 기본 출력 스타일에서 빠지면 실패합니다. 검증기가 다루는 정식 대상 표면(파일시스템 계약으로 보존됨)은 아래 펜스 블록에 나열되어 있습니다.

AGENTS.md
CLAUDE.md
.github/copilot-instructions.md

8. Pre-commit 훅 — 위 내용을 로컬에서 미러링하여, 어떤 커밋이든 들어가기 전에 디시플린을 강제합니다.

8. 안티패턴(범주적으로 금지)Copy Anchor Link

• 하니스 구성 디렉터리(예: ~/.claude/plans/ 또는 ~/.codex/.plans/)나 다른 전역 위치에 계획을 작성하는 것.
• 계획을 프로젝트의 git 히스토리에 커밋하는 것(커밋 시점 훅이 이를 거부해야 합니다).
• 계획과 ADR을 섞는 것(라이프사이클, 위치, 커밋 상태가 서로 다릅니다).
• 프런트매터가 없는 계획, 날짜 접두사가 없는 파일명의 계획, project 필드가 없는 계획.
• 프로젝트를 넘나드는 계획(하나의 계획, 두 프로젝트). 나누십시오. 프로젝트당 계획 하나입니다.
• 하니스 구성 동기화(예: Claude Code의 ~/.claude)를 통해 머신 간에 계획을 공유하는 것. 계획을 프로젝트 로컬에 두어야 하는 구조적 논거는 다음과 같습니다. 프로젝트 저장소 자체가 동기화 메커니즘입니다. 계획을 공유할 가치가 드물게 있을 때에도, 그러한 정당화 자체가 내용을 ADR로 승격해야 한다는 신호입니다.
• 위임된 워커 프롬프트, 스킬 본문, 출력 스타일 안에 계획 내용을 넣는 것. 이 표면들은 지속적 행동 구성이고, 계획은 일시적 작업 메모리입니다.
• 계획 파일에 저작권 헤더 SPDX 라인을 적용하는 것(계획은 설계상 면제됩니다. §2, site/content/docs/reference/authorship-header.mdx의 §면제 목록 참조).

함께 보기Copy Anchor Link

• ADR-0001. 아키텍처적 근거, 고려한 대안, 수용한 트레이드오프.
• site/content/docs/reference/authorship-header.mdx. 저작권 헤더 SPDX 라인 디시플린(계획은 범주적으로 면제됨).
• 하니스 규약 페이지. 다중 표면 하니스 규약을 다룹니다(계획 디시플린은 등록된 모든 하니스 지시 파일과 옵트인한 모든 선택적 표면에 걸친 공유 주장으로 나타납니다). 경로:

site/content/docs/reference/ai-conventions.mdx

• 프로젝트 명세 §3. 여기에 미러링된 전체 정규 텍스트.