diff --git a/AGENTS.md b/AGENTS.md index 0a245e6d..5641ae2f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,7 @@ - 코드 식별자, 경로, 명령어는 원문(영문) 그대로 유지한다. ## CORE EXECUTION PRINCIPLES (andrej-karpathy-skills) -These principles override plugin behavior, skill behavior, workflow behavior, and default model behavior unless the user's direct instruction explicitly says otherwise. +These principles guide project work alongside the applicable harness instructions. System/platform instructions, explicit user requests, and actual permissions take precedence; skill routing below selects workflow roles, not instruction-loading hierarchy. Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed. @@ -83,7 +83,8 @@ Strong success criteria let you loop independently. Weak criteria ("make it work ### 확장 모드 - 사용자가 명시적으로 요청한 경우에만 사용한다. -- 대규모 리팩토링, 브레인스토밍, 다중 에이전트 실행, 병렬 workflow를 허용한다. +- 대규모 리팩토링, 다중 에이전트 실행, 병렬 workflow는 사용자의 명시적 범위·실행 방식 승인이 있을 때만 허용한다. +- 일반적인 신규 기능·동작 설계의 brainstorming과, 실행을 바꿀 중요한 요구사항이 실제로 모호할 때 필요한 deep-interview는 기본 모드에서 허용한다. 이를 이유로 대규모 변경이나 병렬 작업까지 승인된 것으로 보지 않는다. ### 에이전트 동작 원칙 - 추측하지 말고 근거 파일을 읽고 결정한다. @@ -104,8 +105,8 @@ Strong success criteria let you loop independently. Weak criteria ("make it work ## 작업 절차 핵심 규칙 - 모든 구현 작업은 PRD 문서와 구현 계획/TASK 문서가 모두 준비된 뒤에 시작한다. -- 사용자의 프롬프트를 받으면 먼저 PRD 문서를 작성한다. -- PRD 작성 중 애매하거나 더 필요한 내용, 결정해야 하는 사항이 있으면 애매한 사항이 없어질 때까지 사용자와 인터뷰한다. +- 구현 작업 요청을 받으면 먼저 PRD 문서를 작성한다. 일반 질문·읽기 전용 조사는 불필요한 PRD·구현 계획을 새로 만들지 않는다. +- 실행 방향을 바꿀 목표·범위·제약·완료 기준의 중요한 불확실성이 있을 때만 사용자와 인터뷰한다. 코드베이스에서 확인할 수 있는 사실은 직접 조사하고, 이미 명확하거나 승인된 결정은 다시 열지 않는다. - 인터뷰 내용을 PRD에 반영한 뒤, PRD를 기준으로 계획/TASK 문서를 작성하고 그 문서에 따라 필요한 내용만 최소 구현한다. - 문서는 `docs/[날짜]_구현할내용한글/` 아래에 `prd.md`, `plan-task.md`로 만든다. - `docs/[날짜]_구현할내용한글/prd.md` @@ -140,6 +141,18 @@ Strong success criteria let you loop independently. Weak criteria ("make it work ## Agent skills +### 스킬 선택과 작업 단계 +- Superpowers가 사용 가능하면 기본 개발 프로세스로 사용한다. 스킬은 작업 유형을 분류한 뒤 프로세스 담당을 먼저 정하고, 필요한 도메인 전문 스킬만 해당 단계에 보완한다. 매 단계 담당은 하나로 유지한다. +- 하네스가 지침을 어떻게 불러오는지는 플랫폼이 정한다. 이 순서는 작업 단계의 역할 순서이며, 자동 선택이나 호출을 보장하지 않는다. 현재 설치된 스킬 정의·메타데이터·권한·호출 가능성을 확인하고, 사용할 스킬의 실제 지침을 읽는다. +- using-superpowers의 진입 지침이 이미 로드되었다면 다시 로드하지 않는다. 명확한 질문·조사는 읽기 전용으로 답한다. 신규 설계는 brainstorming, 구현 전 계획은 writing-plans, 버그는 systematic-debugging 후 test-driven-development(TDD), 구현 단계 테스트는 TDD, 완료 판정은 verification-before-completion, 요청된 코드 리뷰는 requesting-code-review가 담당한다. +- 요구사항 인터뷰는 목표·범위·제약·완료 기준의 중요한 불확실성이 남을 때만 deep-interview로 분리한다. 코드베이스에서 확인할 수 있는 사실은 직접 조사한다. 설계가 승인되었거나 이미 명확하면 다시 열지 않는다. +- 도메인 용어·용어집·ADR 변경은 domain-modeling이 담당한다. 신규 모듈 설계에는 codebase-design, 공개 API 계약에는 api-and-interface-design, 보안 설계·구현·리뷰에는 security-and-hardening을 해당 Superpowers 단계에서 보완한다. +- 기존 의존성 설계 검토는 requesting-code-review와 codebase-design, 개선 후보 탐색은 읽기 전용 조사와 codebase-design으로 한다. grilling은 사용자가 구체적 결정의 스트레스 테스트를 요청하거나 승인된 개선 흐름의 후보를 선택한 경우에만 연결한다. +- improve-codebase-architecture와 setup-matt-pocock-skills는 사용자가 해당 스킬을 명시 선택한 경우에만 실행한다. 일반 아키텍처·설정 요청이나 접근 권한 승인을 명시 호출로 간주하지 않는다. +- 계획 실행은 executing-plans와 subagent-driven-development 중 실제 전제와 승인된 실행 방식에 맞는 하나만 선택한다. 격리·도구·권한·스크립트 전제를 먼저 확인하고 승인 없는 다중 에이전트·커밋·게시를 실행하지 않는다. +- 비구현 작업은 필요한 문서·검증만 적용한다. 후속 작업은 기존 PRD와 계획을 읽고 첫 미완료 Task부터 재개한다. +- 작업 분류, 기본 경로, 스킬 중복, 플랫폼별 호출 제약은 [docs/agents/skill-routing.md](docs/agents/skill-routing.md)를 읽는다. 이 Markdown 링크는 자동 지침 확장이 아니므로 비단순 작업 분류나 역할 중복 해소 시 직접 읽는다. + ### Issue tracker 이슈는 `.scratch//`의 로컬 Markdown으로 관리한다. 상세 규칙은 `docs/agents/issue-tracker.md`를 참고한다. diff --git a/docs/agent-guides/work-plan-docs.md b/docs/agent-guides/work-plan-docs.md index 7b591f4e..7c4756eb 100644 --- a/docs/agent-guides/work-plan-docs.md +++ b/docs/agent-guides/work-plan-docs.md @@ -12,10 +12,13 @@ ## 작업 계획 문서 규칙 (docs) - 모든 구현 작업은 PRD 문서와 구현 계획/TASK 문서가 모두 준비된 뒤에 시작한다. -- 사용자가 프롬프트를 입력하면 먼저 PRD 문서를 작성한다. -- PRD 작성 중 애매하거나 더 필요한 내용, 결정해야 하는 사항이 있으면 애매한 사항이 없어질 때까지 사용자와 인터뷰한다. +- 구현 작업 요청을 받으면 먼저 PRD 문서를 작성한다. 일반 질문·읽기 전용 조사는 불필요한 PRD·구현 계획을 새로 만들지 않는다. +- 실행 방향을 바꿀 목표·범위·제약·완료 기준의 중요한 불확실성이 있을 때만 deep-interview로 한 번에 한 질문씩 확인한다. 코드베이스에서 알 수 있는 사실은 직접 조사하고, 이미 명확하거나 승인된 결정은 다시 열지 않는다. - 인터뷰로 확정한 내용을 PRD 문서에 보강한 뒤, 해당 PRD를 기준으로 구현 계획/TASK 문서를 작성한다. - 구현은 계획/TASK 문서를 기준으로 필요한 내용만 최소 범위로 진행한다. +- Superpowers brainstorming/plan의 기본 문서 경로 대신 이 저장소의 `docs/YYYYMMDD_작업명/prd.md`와 `plan-task.md`를 정식 문서로 사용한다. 승인된 결정을 보존하고 별도 설계·계획 사본이나 자동 커밋을 만들지 않는다. +- 후속 작업은 기존 PRD와 계획/TASK를 읽고 첫 미완료 Task부터 재개한다. 범위가 바뀌었을 때만 계획을 갱신하고, 계획이 없거나 바뀐 경우에만 writing-plans를 선택한다. +- 각 단계의 책임자, 결정사항, 남은 질문, 정식 문서 경로, 테스트·증거를 다음 단계에 인계한다. 실행 방식은 사용자가 정한 방식과 실제 하네스 기능을 따른다. ### 기준 샘플 - 문서 샘플의 기준 위치는 `docs/sample/`이다. diff --git a/docs/agents/skill-routing.md b/docs/agents/skill-routing.md new file mode 100644 index 00000000..39da3ffc --- /dev/null +++ b/docs/agents/skill-routing.md @@ -0,0 +1,62 @@ +# 스킬 라우팅 정책 + +## 적용 원칙 +- 지침을 읽고 적용하는 계층은 Codex/OpenCode 하네스가 결정한다. 시스템·플랫폼 지침, 명시적 사용자 요청, 실제 권한이 우선하며 이 문서는 작업 단계별 기본 역할을 정한다. +- Superpowers가 실제 사용 가능하면 주 개발 프로세스다. 작업 유형을 분류하고 프로세스 스킬을 먼저 정한 뒤 필요한 전문 스킬만 해당 단계에 추가한다. 한 단계에 프로세스 책임자는 하나다. +- 스킬을 사용하기 전에 현재 설치본의 SKILL.md, frontmatter, 관련 부속 지침을 읽는다. 실제 레지스트리·권한·하네스 기능을 확인하며 자동 선택·호출을 보장하지 않는다. +- 권한이 없거나 스킬이 제공되지 않으면 지원되는 범위의 수동 절차만 수행하거나 제한을 알린다. 명시 전용 스킬을 우회 호출하지 않는다. +- using-superpowers가 이미 로드되었으면 재호출하지 않는다. 아래 TDD는 실제 설치 스킬 이름 `test-driven-development`를 뜻한다. + +## 기본 라우팅 + +| 요청 유형 | 주 프로세스와 순서 | 필요한 보완 및 제외 | +|---|---|---| +| 일반 질문·조사 | 읽기 전용 조사 | 구현 루프는 요구하지 않는다. | +| 신규 기능·동작 설계 | brainstorming이 기본 설계 책임자이며 남은 설계 결정을 정리하고 사용자 승인 후 PRD·계획 | 중요한 요구 불확실성만 deep-interview. 이미 명확하거나 승인된 설계는 다시 열지 않는다. | +| 용어·도메인 모델·ADR | 모델 정리 자체가 요청이면 domain-modeling이 담당 | 개발 중 모델 변경이면 현재 Superpowers 단계의 전문 보완으로 연결한다. 기존 glossary를 읽기만 할 때는 호출하지 않는다. | +| 신규 모듈 인터페이스 | 설계 단계 brainstorming | 인터페이스·seam 설계에는 codebase-design. 기존 의존성 검토를 신규 설계로 가장하지 않는다. | +| 기존 모듈 의존성 설계 검토 | requesting-code-review로 읽기 전용 검토 | codebase-design 기준을 보완하고, 요청하지 않은 신규 설계·grilling·리팩터링은 시작하지 않는다. | +| REST/API 공개 계약 | 설계 단계 brainstorming | 계약 설계에 api-and-interface-design, 실제 보안 경계가 있으면 security-and-hardening. | +| 보안 설계·구현 | 현재 단계의 Superpowers 프로세스 | 보안 관련 사용자 입력, 인증, 민감 데이터, 외부 연동에 security-and-hardening. | +| 버그 수정 | systematic-debugging으로 근본 원인 확인, 이어서 TDD | 일반 탐색은 조사 보조일 뿐 디버깅 책임자를 대체하지 않는다. | +| 구현 계획 작성 | writing-plans | 저장소 PRD·plan-task 경로 규칙을 따른다. 계획이 없거나 변경된 경우에만 작성·갱신한다. | +| 계획 실행 | 아래 실행 방식 중 하나만 선택 | 사용자의 실행 방식과 권한·기능을 확인한다. | +| 테스트 구현 | TDD가 구현 테스트 단계를 담당 | 단순 읽기 전용 조사·문서 작업은 계획의 대체 검증 규칙을 따른다. | +| 코드 리뷰 요청·완료 판정 | 리뷰는 requesting-code-review, 완료 확인은 verification-before-completion | 필요한 기준만 전문 스킬에서 보완한다. 리뷰 패널을 중복 구성하지 않는다. | +| 리뷰 피드백 처리 | receiving-code-review | 근거를 확인하고 확정 수정은 계획에 회귀 Task로 기록한다. | +| 아키텍처 후보 조사 | 일반 읽기 전용 조사와 codebase-design | improve-codebase-architecture는 사용자가 스킬을 명시 선택한 경우에만 실행한다. | +| CI/CD 파이프라인 | 해당 변경 단계의 Superpowers 프로세스 | 파이프라인 변경에 ci-cd-and-automation만 보완한다. | +| 실제 UI 작업 | 해당 변경 단계의 Superpowers 프로세스 | 사용자 UI 변경에 frontend-ui-engineering만 보완한다. | +| 실제 관측성·성능 변경 | 해당 변경 단계의 Superpowers 프로세스 | 계측에는 observability-and-instrumentation, 측정된 성능 문제에는 performance-optimization을 각각 필요한 경우만 보완한다. | + +일반 모드에서 brainstorming은 신규 설계에 허용한다. 요청이 이미 충분히 명확하면 질문을 위해 질문하지 않는다. deep-interview 종료 기준은 점수 0.20 이하이면서 중요한 미해결 불확실성이 없어야 한다. 중요한 명확성 차원이 0.50 이하라면 전체 점수가 낮아도 확인을 계속한다. 점수는 휴리스틱이며 PRD에 결정 요약을 재사용하고 brainstorming은 남은 설계 결정부터 잇는다. + +grilling은 사용자가 구체적인 계획·대안을 스트레스 테스트해 달라고 요청했거나, 명시적으로 선택한 아키텍처 개선 흐름에서 후보를 고른 뒤에만 사용한다. 일반적인 설계 질문에 자동 적용하지 않는다. brainstorming·deep-interview와 grilling의 질문 루프를 동시에 돌리지 않는다. 승인된 설계·계획을 다시 승인받는 중복 게이트나 문서를 만들지 않는다. + +## 실행 방식과 인계 +- executing-plans와 subagent-driven-development는 대안이며 같은 실행 단계에서 함께 쓰지 않는다. 사용자가 고른 방식을 우선하고, 선택이 없으면 저장소 기본은 순차적인 세션 내 실행이다. +- 독립 Task와 실제 하위 에이전트 기능이 있고, 범위와 실행 방식이 명시 승인된 때만 병렬 실행 또는 subagent-driven-development를 선택한다. codebase-design의 design-it-twice 병렬 에이전트도 이 제약을 따른다. +- 두 실행 스킬의 격리 worktree, 계획 ledger/script, main/master 승인 조건을 시작 전에 확인한다. 의존 지침을 읽고 해당 하네스의 도구·스크립트 호환성을 추정하지 않는다. 필수 전제나 승인 조건이 충족되지 않으면 좁은 장애를 알리고 확인을 요청하며 우회하거나 실행한 척하지 않는다. +- 스킬 예시의 자동 커밋·병합·푸시·삭제는 실행하지 않는다. 검증 뒤 통합 선택이 필요한 경우에만 finishing-a-development-branch를 사용하며 자동 게시하지 않는다. +- 단계 전환 때 다음 기록을 재사용한다. 별도 프레임워크나 파일을 만들지 않는다: 요청 유형, 단계 책임자, 확정 결정, 남은 질문, 정식 문서, 테스트·증거. +- 본 저장소의 `docs/YYYYMMDD_작업명/prd.md`와 `plan-task.md`가 정식 문서다. brainstorming/writing-plans의 기본 저장 경로보다 이 경로를 우선하며 결정을 복사·재작성하지 않는다. 후속 요청은 기존 문서를 읽고 첫 미완료 Task에서 잇는다. +- systematic-debugging은 버그의 원인 조사, TDD는 수정 테스트, verification-before-completion은 완료 판정, requesting-code-review는 하나의 리뷰 절차를 맡는다. 리뷰 전문 기준은 security-and-hardening 또는 codebase-design에서 실제 필요에 따라 보완한다. 완료 뒤 피드백 수정은 receiving-code-review로 처리한다. + +## 여섯 중복 조합 + +| 조합 | 겹치는 부분 | 고유 책임과 선택 우선순위 | +|---|---|---| +| brainstorming / deep-interview | 설계 전 요구 이해 | brainstorming은 설계 대화 전체의 기본 책임자. 중요한 요구사항 공백이 있을 때 deep-interview를 요구 명료화 하위 단계로만 사용하고 결과를 넘긴다. | +| brainstorming / grilling | 사용자에게 질문하고 선택을 구함 | brainstorming은 신규 설계. grilling은 명시 요청된 구체 계획의 적대적 스트레스 테스트 또는 승인된 개선 흐름의 후보 선택 후에만 사용한다. 질문 루프를 병행하지 않는다. | +| brainstorming / codebase-design | 새 인터페이스 결정 | brainstorming이 설계·사용자 의도를 담당하고, codebase-design은 모듈 깊이·interface·seam의 전문 기준을 제공한다. 새 설계에서 필요한 경우만 함께 쓴다. | +| codebase-design / api-and-interface-design | 인터페이스·경계 설계 | codebase-design은 모듈·seam·depth, api-and-interface-design은 공개 API 계약·호환성과 규약을 담당한다. API 계약이 실제 대상일 때만 후자를 추가한다. | +| requesting-code-review / security-and-hardening | 위험·결함 판단 | requesting-code-review가 리뷰 절차와 판정을 소유한다. 보안 민감 범위에만 security-and-hardening의 기준을 리뷰 렌즈로 쓴다. 별도 리뷰 루프를 열지 않는다. | +| systematic-debugging / general 탐색 | 근거를 찾는 코드 조사 | 버그가 보고되면 systematic-debugging이 가설·원인 검증을 소유하고, general 탐색은 사실 수집의 보조만 맡는다. 일반 조사는 버그 책임자를 대체하지 않는다. | + +## 명시 호출, 권한, 플랫폼 차이 +- improve-codebase-architecture와 setup-matt-pocock-skills는 설치된 정의에서 `disable-model-invocation: true`, `agents/openai.yaml`에서 `allow_implicit_invocation: false`가 확인된 명시 호출 전용 스킬이다. 일반 요청의 권한 승인만으로 명시 호출이 되지 않는다. 이 저장소는 하네스와 무관하게 사용자의 정확한 명시 선택을 요구한다. +- setup은 일반 개발 중 실행하지 않는다. 이 저장소에는 이미 로컬 이슈 추적과 도메인 문서 안내가 있다. architecture 개선 스킬은 임시 HTML 후보 보고 뒤 사용자가 선택한 경우에만 grilling으로 이어진다. +- OpenCode의 `metadata["opencode/autoinvoke"]: "false"`는 자동 안내 노출을 제한하며 정확한 이름의 수동 로드는 별도 경로다. Codex의 `policy.allow_implicit_invocation: false`는 암묵 호출을 막고 명시 `$skill` 호출 경로는 유지한다. 두 경로 모두 실제 접근 권한은 별도로 준수한다. `disable-model-invocation`은 모든 호스트에서 강제되는 기능으로 간주하지 않는다. +- `permission.skill`의 allow/ask/deny와 하네스의 실제 접근 가능 여부를 구분한다. ask는 승인 요청, deny는 호출 금지이며 우회할 수 없다. 에이전트별 제한과 현재 설치·활성 상태도 확인한다. 전역 설정과 설치된 메타데이터는 수정하지 않는다. +- 설치된 스킬의 존재는 현재 세션에서 호출 가능하다는 증거가 아니다. 조사 시점에는 Codex CLI의 Superpowers 설치·활성과 OpenCode의 플러그인 설정·스킬 광고가 확인됐지만, 개별 자동 선택은 미검증이다. 실행할 때의 레지스트리와 권한을 다시 확인하고, 사용할 수 없으면 가능한 수동 절차를 알리며 명시 전용 제한을 우회하지 않는다. +- gstack은 설치·호출하지 않는다. 보조 Addy 스킬은 실제 CI/CD, UI, 계측, 측정된 성능 작업에 한해 필요한 것만 선택한다. 참조 체크리스트가 설치본에서 누락된 경우 읽은 지침만 적용하고, 누락 자료에 의존하는 검증은 수행 완료로 주장하지 않는다.