36 lines
6.6 KiB
Markdown
36 lines
6.6 KiB
Markdown
# 에이전트 실행 정책 상세 가이드
|
|
|
|
이 문서는 `AGENTS.md`의 Skill Orchestration 및 우선순위 정책을 보완한다. 지시 우선순위의 기준은 root `AGENTS.md` 하나이며, 이 문서는 별도 계층을 만들지 않는다.
|
|
|
|
## 충돌 및 소유권
|
|
|
|
| 조합 | 공유 작업 | 고유 소유권 | 트리거·순서·우선 |
|
|
|---|---|---|---|
|
|
| `brainstorming` / `deep-interview` | 새 제품 목표와 요구사항 구체화 | brainstorming은 설계, deep-interview는 중요 미결정의 질문/요약 | 목표·범위·제약·성공·맥락의 중요 미결정, 충돌 또는 사용자 요청에서만 deep-interview를 임시 선행 소유자로 쓴 뒤 요약을 기존 PRD에 합치고 brainstorming으로 간다. 확정 사항이면 인터뷰 반복 없이 설계한다. |
|
|
| `brainstorming` / `grilling` | 설계 아이디어와 결정 검토 | brainstorming은 설계안 생성, grilling은 계획·결정·아이디어의 적대적 스트레스 테스트 | 사용자 요청 또는 구체적 대안 비교 시 설계 후 선택적으로 grilling. 모든 설계에 grilling을 붙이지 않는다. 한 번에 하나 질문과 다중 frontier 질문 회차를 병행하지 않는다. |
|
|
| `brainstorming` / `codebase-design` | 모듈 경계 및 설계 판단 | brainstorming은 전체 설계 절차, codebase-design은 모듈 규모와 무관하게 depth/seam/locality 및 exposed interface의 설계 어휘 | 설계 중 구체적인 module seam/interface 문제가 필요할 때 좁게 보완한다. codebase-design만으로 인터뷰나 전체 설계 절차를 대체하지 않는다. |
|
|
| `codebase-design` / `api-and-interface-design` | 모듈/API 경계와 contract | codebase-design은 depth/seam/locality와 module design, api-and-interface-design은 내부·외부 공개 계약의 안정성/errors/compatibility | 내부 type/function 계약이나 REST/GraphQL 계약을 설계할 때 계약 문제는 API 전용 skill owner, seam/depth 문제는 codebase-design owner로 분리한다. 필요한 단계만 순차/보완하고 internal/public 경계로 범위를 제한하지 않는다. |
|
|
| `requesting-code-review` / `security-and-hardening` | 보안 관련 변경 검토 | requesting-code-review는 완료 작업의 단일 리뷰, security-and-hardening은 적용 가능한 보안 기준 | 보안 기준이 필요한 리뷰에서만 좁은 보완으로 사용한다. 별도 보안 리뷰 요구는 보안 범위를 소유하지만 리뷰 절차를 중복하지 않는다. |
|
|
| `systematic-debugging` / 일반 조사 | 실패 현상과 근거 파악 | systematic-debugging은 재현 가능한 버그의 가설 기반 진단, 일반 조사는 질문/정보 수집 | 실패/오동작이면 systematic-debugging으로 원인을 진단한 후 회귀 테스트/TDD, 단일 수정 경로, 검증 순. 버그가 아닌 탐색에는 디버깅 생명주기를 강제하지 않는다. |
|
|
|
|
한 작업의 실행 단계마다 주 소유자는 하나다. 추가 스킬은 좁은 기준만 보완하며 전체 생명주기를 다시 시작하지 않는다. API 계약·보안 보완은 brainstorming의 설계 단계 안에서 수행하고, 설계가 승인되면 빠진 계획 단계로 인계한다. 이미 승인된 설계와 유효한 계획이 있으면 첫 미완료 단계로 이어간다. 설계만 확정된 경우 계획이 없으므로 `writing-plans`로 계획을 먼저 보완한다. grilling은 회차마다 답변을 기다리고, 의존 결정이 모두 정리된 종료 시점에 공유 이해 확인을 받는다.
|
|
|
|
## 호스트 및 권한 경계
|
|
|
|
- Codex의 `agents/openai.yaml` `policy.allow_implicit_invocation: false`는 implicit skill invocation을 막는다. OpenAI 공식 문서상 기본값은 true다.
|
|
- OpenCode `metadata['opencode/autoinvoke']='false'`는 모델 자동 선택 노출만 숨기며, 명시적 호출을 막는 권한 규칙이 아니다. `permission.skill`의 `deny`/`ask`와 agent/tool 권한은 별개다. `disable-model-invocation`은 OpenCode native 설정으로 문서화되어 있지 않다.
|
|
- 현재 OpenCode 도구는 이 두 skill을 광고할 수 있다. `improve-codebase-architecture`와 `setup-matt-pocock-skills`는 설치본에서 `disable-model-invocation: true`, Codex implicit false지만 OpenCode autoinvoke metadata가 없다. 따라서 OpenCode 자동 선택을 backend에서 막는다고 주장하지 않는다. 이 프로젝트 정책상 둘 다 명시 skill-name 요청만 허용한다. Markdown은 backend/hook denial을 강제하지 않는다. 구조 개선 후보 탐색만으로 HTML/브라우저/grilling workflow를 실행 또는 흉내 내지 않는다. 일반 HTML 산출물 요청만으로도 improve skill 호출을 승인한 것이 아니다. 허용된 읽기 전용 `codebase-design` 분석은 별개다. setup 스킬은 별도 일회성 요청에만 쓴다.
|
|
- Markdown 정책은 상위 역할/플랫폼 권한을 덮거나 우회하지 않는다. 설치 스킬 또는 필수 참고 파일이 없으면 제한을 알리고 부분 확인만 수행하며 완전한 검증으로 표현하지 않는다. 메타데이터나 전역 설정 변경으로 제한을 우회하지 않는다. gstack은 어느 단계에서도 사용하거나 설치하지 않는다.
|
|
- Addy의 웹 예시는 해당되는 통제만 참고한다. iOS에 서버 cookie/CSP 같은 설정을 이식하지 않고 실제 SodaLive API와 스타일을 따른다.
|
|
|
|
## 운영 체크
|
|
|
|
- `AGENTS.md`에서 작업 종류를 분류하고 적용 가능한 현재 호스트 스킬 본문을 읽는다. 동일 본문/완료 결과는 재사용한다.
|
|
- 변경 전: 유사 기능 코드를 먼저 찾아 네이밍/예외/응답 패턴을 맞춘다.
|
|
- 변경 중: 공개 API 스키마를 임의 변경하지 말고 작은 단위로 안전하게 수정한다.
|
|
- 변경 후: 영향 범위 파일에 대해 빌드/테스트/로그/다국어 키를 점검한다.
|
|
- 커밋 작업 시작 시 `AGENTS.md`의 호스트별 방법으로 `commit-policy`를 먼저 읽고, 커밋 직후 메시지 검증 스크립트를 실행한다. 커밋 자체는 사용자 요청이 있을 때만 한다.
|
|
- 빌드·테스트·검증 명령은 `docs/agent-guides/build-test-verification.md`, 스타일은 `docs/agent-guides/code-style.md`, 문서 절차는 `docs/agent-guides/documentation-policy.md`를 따른다.
|
|
- 작은 변경은 단일 경로로 한다. 다중 에이전트 또는 병렬 확장은 명시적 허용이 있고 실제 독립 작업인 경우에만 한다. 계획 실행은 `executing-plans` 또는 `subagent-driven-development` 중 하나다.
|
|
- 문서 전용 작업은 TDD를 형식적으로 적용하지 않는다. 해당 대체 검증 근거와 실제 실행 결과를 작업 계획에 기록한다.
|