SeemSeam/plan-tree

계획 트리 (Plan Tree)

이 스킬을 지속 가능한 프로젝트 방향, 실행 준비 상태, 진행 상태 및 Markdown 계획 트리를 위한 계획 워크플로우 권위자로 사용하세요. 사용자의 의도, 기존 문서 스타일, 추론 과정 및 계획-배포 증거를 세션과 에이전트 전반에 걸쳐 보존합니다.

필수 운영 모드

모든 plan-tree 작업에 대해, 편집 또는 구현 전에 작업 모드를 결정합니다.

• 모드가 불명확한 경우 clarify 또는 ready-check를 기본값으로 사용하고, execute-ready는 사용하지 마십시오.
• 기존 plan-tree 상태를 사용할 수 있는 경우, 방향을 변경하기 전에 관련 진입점과 현재 계획 상태를 검사합니다.
• 솔루션이 구현하기에 충분히 성숙하지 않은 경우, 계획 및 명확화 모드로 유지합니다. 사용자의 의도를 목표, 비목표, 제약 조건, 옵션, 트레이드오프, 위험, 종속성, 수락 기준, 검증 경로, 출시 또는 롤백 노트로 확장합니다.
• 핵심적인 모호함(범위, 접근 방식, 영향받는 표면, 예상 동작, 수락 기준, 검증 경로 또는 위험)이 남아 있는 동안에는 주요 프로젝트 표면에서 공식 구현을 시작하지 마십시오.
• 소규모의 격리된 프로토타입이나 샘플은 방향을 검증하고 프로덕션 경로와 명확하게 분리된 경우에만 허용됩니다.
• 계획은 핵심 결정에 대해 '코딩하면서 알아내기'에 의존하지 않고 실행할 수 있을 때에만 구현 준비가 완료됩니다.
• 구현이 배포된 후에는 계획 트리 상태, 배포 증거, 결정, 미해결 질문 및 인계 노트를 업데이트하여 구현이 지속 가능한 계획 상태로 다시 프로젝션되도록 합니다.

작업 모드

작업 시작 시 하나의 기본 모드를 선택하고, 상태가 변경될 때만 전환합니다.

• clarify: 의도, 범위, 제약 조건, 성공 기준 또는 트레이드오프가 불명확합니다. 필요할 때 집중된 질문을 통해 논의하고, 유용한 경우 명확화 결과를 plan-tree 파일에 기록합니다. 주요 프로젝트 구현 파일을 편집하지 마십시오.
• shape-plan: 방향은 대부분 알려져 있지만 구체적인 솔루션 맵이 필요합니다. 로드맵 항목, 주제, 가정, 결정, 위험, 수락 기준 및 미해결 질문을 생성하거나 업데이트합니다.
• ready-check: 사용자가 구현하거나 진행하려 하지만 준비 상태가 불확실합니다. 범위, 접근 방식, 영향받는 표면, 수락 기준, 검증 및 위험이 충분히 명시적인지 평가합니다. 그렇지 않은 경우 clarify 또는 shape-plan으로 돌아갑니다.
• resume: 이전 작업을 계속합니다. 루트 진입점, 관련 기준선, 대상 계획 README, 구현 상태, 로드맵 및 활성 연결된 파일만 읽습니다. 편집 전에 현재 단계, 활성 TODO, 차단기, 다음 대상 및 마지막 검증을 요약합니다.
• execute-ready: 계획이 구현하기에 충분히 준비되었습니다. 합의된 범위 내에서만 프로젝트 파일을 수정한 다음, plan-tree 상태와 증거를 업데이트합니다.
• status-update: 작업 또는 검토 후 로드맵 상태, 구현 상태, 마지막 배포, 다음 대상, 차단기, 인계 또는 계획 레지스트리를 업데이트합니다.
• archive: 대체된 세부 사항, 이전 상태 스냅샷, 수락된 증거 또는 참고 전용 자료를 검색 링크를 유지하면서 활성 파일에서 이동합니다.
• normalize: 기존 계획 트리 또는 혼합 역할 소스 파일을 더 작은 검색 단위로 재구성합니다. 먼저 indexes/migration-map.md 또는 가장 가까운 유용한 인덱스를 생성하거나 업데이트하고, 소스 자료를 검색 역할별로 분류하고, 짧은 캡슐과 리더-태스크 세부 샤드를 생성하고, 수락된 검증을 evidence/로 이동하고, 이전 상태 또는 추론 내러티브를 history/로 이동합니다. 명시적으로 승인되지 않는 한 소스 자료를 삭제하지 마십시오.
• audit 또는 migrate: 일관성, 검색, 드리프트, 레거시 루트 또는 마이그레이션 매핑을 검사합니다. 사용자가 수리, 정규화 또는 마이그레이션을 요청하지 않는 한 읽기 전용으로 기본 설정합니다.

문서화 작업(예: idea, promote, question, decision)은 이러한 모드 내에서 발생합니다:

• idea: 낮은 커밋먼트의 생각을 ideas/inbox.md 또는 로컬 등가물에 추가합니다.
• promote: 아이디어를 로드맵 항목, 주제, 미해결 질문 또는 결정으로 승격시키고 원본 아이디어를 링크합니다.
• question: 미해결 질문을 추가, 좁히기 또는 해결합니다.
• decision: 안정적인 결정 레코드를 생성하거나 업데이트합니다.

핵심 워크플로우

모든 plan-tree 작업에 대해:

1. 작업 모드와 허용된 쓰기 표면을 선택합니다: 없음, plan-tree 전용, 격리된 프로토타입 또는 프로젝트 파일 + plan-tree 업데이트.
2. plantree 루트, 대상 계획 루트 및 사용자 의도를 식별합니다.
3. 루트 인덱스와 관련 로드맵, 상태, 주제, 결정, 질문, 아이디어, 이력 또는 기준선 파일만 읽습니다.
4. 작업이 명시적으로 재구성하는 것이 아닌 한 기존 진입점, 등록된 루트, 폴더 이름, 문서 스타일 및 권한 순서를 유지합니다.
5. 활성 로드맵, 인계 및 주제 캡슐 파일을 작게 유지합니다. 세부 정보, 증거 및 이력을 활성 상태에서 이동합니다.
6. 지속 가능한 파일을 추가, 이동, 승격, 아카이빙 또는 분할할 때 인덱스, 검색 헤더 및 링크를 업데이트합니다.
7. 응답하기 전에 최종 검사를 실행합니다.
8. 변경된 파일, 미해결 질문, 활성 모드 및 해당되는 경우 다음 유용한 유지보수 작업을 보고합니다.

기본 파일 시스템

plan-tree 관리 자료의 기본 크로스-프로젝트 파일 시스템으로 docs/plantree/를 사용합니다. 이는 plantree 시스템 루트이자 레지스트리이며, 단일 계획 루트가 아닙니다. 이름은 공급자 또는 프레임워크 네이티브 plans/ 폴더와의 충돌을 피합니다.

기본 구조:

• docs/plantree/README.md: 레지스트리, 권한 순서, 기준선 링크, 활성 계획 테이블 및 트리 읽는 방법.
• docs/plantree/baseline/: 모듈 맵, 런타임 흐름, 상태/스토리지 경계, 테스트/릴리스 게이트 및 위험 핫스팟과 같은 프로젝트 전체 컨텍스트.
• docs/plantree/plans/<NNN>-<plan-name>/: 안정적인 숫자 순서, 로드맵/상태, 주제, 결정, 미해결 질문, 증거, 인덱스 및 프로젝트에 확립된 명명 규칙이 없는 경우 선택적 이력을 포함하는 특정 계획 루트.
• docs/plantree/ideas/inbox.md: 낮은 커밋먼트 아이디어 인박스.

발견 순서:

1. 명시적 사용자 경로가 제공된 경우 이를 사용합니다.
2. 그렇지 않고 docs/plantree/README.md가 존재하는 경우 docs/plantree/를 사용합니다.
3. 그렇지 않으면 현재 작업에 대해 명확히 활성화된 다른 확립된 트리를 유지합니다. 사용자가 채택, 정규화 또는 마이그레이션을 요청한 경우에만 마이그레이션을 평가합니다.
4. 그렇지 않으면 계획을 생성하거나 업데이트하기 전에 docs/plantree/를 부트스트랩합니다.

새로운 특정 계획은 로컬 규칙이 없는 경우 기본적으로 docs/plantree/plans/<NNN>-<plan-name>/으로 설정되며, docs/plantree/README.md에 등록되어야 하고, 글로벌 컨텍스트를 복사하는 대신 관련 기준선 파일에 링크해야 합니다. 사용자가 명시적으로 마이그레이션을 승인하지 않는 한 확립된 번호가 없거나 다르게 구성된 트리는 유지합니다.

첫 사용

docs/plantree/가 없는 프로젝트에서 plan-tree 작업이 호출되면, 사용자가 명시적으로 파일 생성을 요청하지 않는 한 최소한의 루트를 생성합니다.

부트스트랩:

• 루트: docs/plantree/README.md
• 기준선: baseline/README.md, module-map.md, runtime-flows.md, storage-and-state.md, test-and-release-gates.md, risk-hotspots.md
• 컨테이너: plans/, ideas/inbox.md

부트스트랩 콘텐츠는 간결하고 증거 기반으로 유지합니다. 충분한 코드가 검사되지 않은 경우 프로젝트 사실을 임의로 만들지 말고 알 수 없음 / 인벤토리 필요라고 작성합니다. 오래되었거나 익숙하지 않은 프로젝트의 경우 상세 계획을 생성하기 전에 기준선을 구축하거나 갱신합니다.

계획 모델

계획 루트를 생성하거나 유지 관리할 때 다음 역할을 사용하고 이름을 로컬 규칙에 맞게 조정합니다:

• README.md: 범위, 권한, 파일 맵, 읽기 경로 및 plantree 루트인 경우 활성 레지스트리. 활성 계획 테이블의 경우 경량 ID를 사용할 때 ID | 계획 | 영향받는 모듈 | 상태 | 현재 단계 | 마지막 배포 | 다음 대상을 선호합니다.
• roadmap.md: 트리가 이미 다른 모델을 사용하지 않는 한 완료, 진행 중, 다음, 연기됨으로 그룹화된 지속 가능한 상태.
• implementation-status.md: 진행 중 계획에만 해당하는 간단한 운영 인계. 계획 중이거나 연기된 계획은 일반적으로 이 파일이 필요하지 않습니다.
• open-questions.md: 미해결 질문만.
• topics/: 지속 가능한 컨텍스트, 솔루션 맵, 옵션, 제약 조건, 수락 기준, 구현 노트, 리포지토리 위생 계획 및 위험 분석. 최상위 주제 파일은 짧은 캡슐로 유지합니다. 큰 주제는 세부 샤드가 있는 주제 폴더로 분할합니다.
• decisions/: 안정적인 결정. 집합이 커지면 인덱싱합니다.
• evidence/: 현재 또는 수락된 검증 레코드, 검토 결과, 아티팩트 노트 및 이와 별도로 검색해야 하는 경우 증거 인덱스.
• history/: 수락된 체크포인트 로그, 이전 검토, 폐기된 스냅샷, 아카이브 전용 소스 노트 및 대체된 세부 사항.
• indexes/: 로컬 인덱스가 탐색 문제를 해결하는 경우 단계 맵, 주제 맵, 권한 맵, 마이그레이션 맵 및 증거 맵과 같은 선택적 검색 맵.
• ideas/: 루트 수준의 아이디어가 충분히 구체적이지 않은 경우 선택적 낮은 커밋먼트 아이디어 풀.

템플릿 생성, 대규모 트리 처리, 결정/상태/인계/이력/인덱스 파일 유지 관리, 리포지토리 위생 계획 추가 또는 상세 최종 확인 체크리스트가 필요할 때 references/maintenance-patterns.md를 읽습니다.

경량 ID 및 모듈 분류

프로젝트에 확립된 계획 명명 규칙이 없는 경우, 작업 데이터베이스를 만들지 않고 파일 시스템 스캔 및 지속 가능한 참조를 개선하기 위해 경량 ID를 사용합니다:

• 프로젝트 전체에 P001, P002 등의 계획 ID를 할당합니다. P001을 docs/plantree/plans/001-authentication/과 같은 플랫 루트에 매핑합니다.
• 고정 너비 3자리 십진수를 사용합니다. 유지된 최대 계획 번호에 1을 더한 값을 할당합니다. ID를 재사용하지 말고, 번호를 다시 매겨 간격을 닫지 말며, 우선순위, 상태, 모듈, 소유자, 작업자, 단계 또는 날짜를 인코딩하지 마십시오.
• 의미론적 슬러그는 안정적이고 소문자 케밥-케이스로 유지합니다. 제목이나 영향받는 모듈은 계획 ID나 디렉토리를 변경하지 않고 변경될 수 있습니다.
• 계획 레지스트리가 작은 동안에는 docs/plantree/README.md에서 ID 및 라이프사이클 등록을 유지합니다. 검색을 개선하는 경우에만 인덱스로 분할합니다. 기본적으로 병렬 할당 원장을 유지하지 마십시오.
• T001과 같은 로드맵 작업 ID는 선택 사항이며 계획-로컬입니다. 안정적인 크로스-파일 참조가 도움이 되는 경우에만 사용합니다. 사용될 때 roadmap.md는 작업 ID, 상태 및 순서에 대한 유일한 활성 권한입니다. 기본적으로 별도의 작업 레지스트리나 작업 폴더를 만들지 마십시오.
• 결정 파일 이름은 001-<decision>.md 규칙을 유지할 수 있습니다. 미해결 질문은 지속 가능한 참조가 도움이 될 때 Q001을 사용할 수 있습니다. 아이디어는 승격될 때까지 번호가 지정되지 않은 상태로 유지됩니다.
• 코드 또는 제품 모듈을 영향받는 모듈과 같은 계획 메타데이터로 취급하며, baseline/module-map.md에 정의된 안정적인 키를 사용합니다. 기본적으로 계획 루트는 플랫하게 유지합니다. 입증된 탐색 필요와 기록된 결정 후에만 모듈 인덱스 또는 물리적 모듈 디렉토리를 추가합니다.
• 동일-변경 일관성을 적용합니다. 한 번의 유지보수 변경으로 권위 있는 파일과 필요한 진입점 요약을 업데이트한 다음, ID, 경로, 모듈 키, 로드맵 고유성, 상태 주장 및 상대 링크를 확인하고 마무리합니다.
• 자동 수리보다 읽기 전용 드리프트 감지를 선호합니다. 관찰된 조정 실패가 비용을 정당화할 때까지 감시자, 자동 번호 재할당, 할당 잠금 또는 복구 저널을 추가하지 마십시오.

이러한 기본값은 점진적입니다. 성숙한 트리의 로컬 ID, 이슈, 티켓 또는 폴더 규칙을 유지하고 그 위에 경쟁 네임스페이스를 계층화하지 마십시오.

동적 상태 및 증거

• 진행 중 계획만 implementation-status.md가 필요합니다. 계획 중 계획은 roadmap.md, 주제, 미해결 질문 또는 결정에서 준비 상태를 표현해야 합니다.
• implementation-status.md는 운영적이고 짧게 유지합니다. 100줄 미만을 선호합니다. 늘어나면 오래된 세부 정보를 아카이브하거나 인덱싱합니다.
• 활성 TODO는 최대 5개의 현재 항목으로 유지합니다. 더 많은 항목은 일반적으로 작업에 로드맵 단계, 주제 또는 분할이 필요함을 의미합니다.
• 로드맵 작업 ID가 사용되는 경우, 두 번째 레지스트리에서 작업 ID를 다시 설명하지 않고 활성 TODO에서 해당 ID를 재사용합니다.
• 해당되는 경우 구체적인 현재 단계, 다음 대상, 마지막 배포, 활성 TODO, 차단됨 및 마지막 검증 또는 인계 노트를 포함합니다.
• 마지막 배포는 가능한 경우 날짜와 함께 커밋, 아티팩트, 테스트 결과, 수락된 체크포인트 또는 기타 증거를 가리켜야 합니다.
• 단계/패키지/게이트 수준 증거에는 evidence/README.md, indexes/evidence-map.md 또는 로컬 등가물을 사용합니다. 대체된 증거 아카이브에만 history/evidence-index.md를 사용합니다. 모든 작은 단계를 거기에 기록하지 마십시오.
• 활성 로드맵/상태 파일은 이전 증거에 링크하고, 반복되는 로그, 이전 자동화 출력, 검토 작업 세부 정보 또는 과거 내러티브를 흡수하지 않아야 합니다.

검색 모델

Plan-tree는 검색 단위 시스템이지 대규모 종합 문서를 키우는 장소가 아닙니다. 모든 지속 가능한 파일은 하나의 주요 역할을 가져야 합니다:

• 진입점 또는 인덱스: 라우팅, 권한 순서, 읽기 경로 및 한 줄 요약.
• 현재 상태: 활성 로드맵, 현재 단계, 차단기, 다음 대상 및 인계.
• 주제 캡슐: 하나의 도메인, 기능, 제약 조건 집합 또는 작업 스트림에 대한 간략한 요약과 세부 샤드에 대한 링크.
• 세부 샤드: 하나의 리더 작업에 대한 계약, 대안, 엣지 케이스, 구현 노트, 출시, 운영, 준비 상태 또는 리포지토리 위생 세부 정보.
• 결정: 컨텍스트와 결과가 포함된 안정적인 선택.
• 증거: 검증 레코드, 검토 결과, 아티팩트 링크, 수락된 테스트 요약 또는 증거 인덱스.
• 이력/아카이브: 대체된 상태, 이전 실행 로그, 마이그레이션된 소스 자료 및 폐기된 세부 사항.

하나의 파일이 동시에 요약, 활성 상태, 결정, 긴 추론, 로그, 증거 및 이력을 담당하게 하지 마십시오. 업데이트가 파일의 역할 경계를 넘을 경우, 먼저 연결된 검색 단위를 생성하거나 업데이트한 다음 활성 파일에는 간결한 요약과 링크만 남깁니다.

이러한 줄 수를 분할 트리거로 사용하되, 엄격한 정확성 테스트로 간주하지 마십시오:

• 루트 README, 계획 README, 로드맵 및 구현 상태: 약 150줄 이하로 유지합니다.
• 주제 캡슐: 약 250줄 이하로 유지합니다.
• 일반 세부 샤드: 약 400줄에서 분할 또는 인덱싱합니다.
• 이력 또는 증거 파일: 약 500줄에서 인덱싱 또는 분할합니다.