llm-wiki/rules/subagent-input-contracts.md

rules/subagent-input-contracts — 서브에이전트/명령 입력 계약

rules/ 의 방법론 규칙. controller(메인 에이전트 또는 /branch-spec 같은 오케스트레이터)가 dispatch 전에 무엇을 모아야 하는가를 agent별 form schema로 고정한다. 목적: agent 가 NEEDS_CONTEXT 로 멈추는 일을 줄이고 되묻지 않는 조립을 가능하게 한다. SSOT 주의 — 각 agent 의 권위 있는 입력 정의는 그 agent 본문(.claude/agents/<name>.md 의 ## Required Inputs)이다. 본 문서는 그것을 재사용 가능한 체크 형태로 요약·참조할 뿐, 값을 복제하지 않는다. 충돌 시 agent 본문이 우선.

원칙 (3-rule)

Rule	의미
C1. Pre-fill	controller 는 dispatch 전에 아래 표의 필수 입력을 모두 채운다. 못 채우면 (a) 자동조사로 보강하거나 (b) 명시적 라벨(UNSUPPORTED_DECISION 등)로 남긴다 — 추측해서 FACT 로 채우지 않는다(CLAUDE.md §11).
C2. Missing → 행동 명시	각 필수 입력에는 누락 시 행동이 정의돼 있다. "조용히 추측" 은 금지. NEEDS_CONTEXT / 자동조사 / 라벨 중 하나.
C3. No SSOT 이중화	본 계약은 agent 본문을 참조만 한다. 입력 값(예: 허용 source_type 목록)은 agent 본문·rules/naming-conventions.md·rules/tag-taxonomy.md 에서 가져온다.

입력 계약 표

표기: 필수 = dispatch 전 반드시 / 선택 = 있으면 사용 / 누락 시 행동 = 빈 채로 dispatch 됐을 때.

/branch-spec <slug> (오케스트레이터 명령)

입력	구분	누락 시 행동
branch_slug	필수	인자 비면 사용자에게 요청(종료)
대상 노트 존재 (raw/branch-notes/<slug>.md)	필수(전제)	없으면 /branch 먼저 안내(종료)
parent (project 또는 parent branch)	필수	노트의 ## Parent 에서 읽음. 없으면 NEEDS_CONTEXT
sources[] (외부 자료 URL 또는 [[raw/...]])	조립 입력	URL → wiki-source-summarizer dispatch. 하나도 없으면 결정마다 자동조사(아래)
decision_candidates[]	조립 입력	source Claim 에서 자동 도출 시도
scope.in[] / scope.out[]	조립 입력	비면 in-scope 만 채우고 out 은 빈 채로 Should-fix 보고

자동조사 bound: 근거 없는 결정 회당 최대 6개 까지 wiki-decision-researcher dispatch. 초과분은 deferred 로 보고(silent 절단 금지). 조사 후에도 근거 없으면 UNSUPPORTED_DECISION + trade-off 한 줄.

/project-spec <slug> <목표> [근거 URL ...] (오케스트레이터 명령)

project-note hub 를 ca-skeleton caliber 로 채우고 끝에 readiness 게이트(rules/project-readiness-gate). /branch-spec 의 hub 짝.

입력	구분	누락 시 행동
project_slug	필수	인자 비면 사용자에게 요청(종료 — 대상 파일 모름)
대상 노트 존재 (raw/project-notes/<slug>.md)	필수(전제)	없으면 /project 먼저 안내(종료)
goal (프로젝트 목표 prose)	필수	종료 말고 AskUserQuestion 으로 물어 받아 진행
owner_decisions[] (범위/우선순위/성공기준 임계)	사용자 소유	추측·UNSUPPORTED 금지 — AskUserQuestion(하네스 내장 툴) 으로 직접 질의
sources[] (URL)	조립 입력	hub 결정 근거는 wiki-source-summarizer(parent = [[raw/project-notes/<slug>]]) dispatch

직접 dispatch: wiki-source-summarizer(§5 hub 소싱) + project-readiness-auditor(§9 게이트) 둘뿐. wiki-decision-researcher(결정별 깊은 대안조사)는 parent_branch 계약상 branch 단계로 이관 — /project-spec 에서 안 부른다. wiki-diagram-reviewer(≥95)는 사용자가 별도 실행(게이트 강제 아님). 자동소싱 bound 6개·초과분 deferred(R3 면제).

차이(/branch-spec 대비): ① 사용자 소유 결정은 UNSUPPORTED 라벨이 아니라 AskUserQuestion(hub in-the-loop), ② 게이트는 readiness(R1~R4) 단일, ③ 사용자 행동으로만 해소되는 Blocking(다이어그램·소유결정)은 Ready-pending-user 로 종료(무한루프 금지).

wiki-source-summarizer

권위: .claude/agents/wiki-source-summarizer.md 의 ## Required Inputs (링크 아님 — Obsidian 은 .claude/ 를 색인하지 않으므로 백틱 코드로만 표기). 요약:

입력	구분	누락 시 행동
url	필수	NEEDS_CONTEXT
source_type (official-doc | company-tech-blog)	필수	다른 값이면 reject
parent + 이 자료가 정당화하는 결정(한 줄)	필수	NEEDS_CONTEXT
claim_id_prefix / file_slug / vendor	선택	slug·URL 에서 도출

wiki-decision-researcher

입력	구분	누락 시 행동
decision_topic	필수	NEEDS_CONTEXT
parent_branch	필수	NEEDS_CONTEXT
constraints (선택 조건/요구사항)	필수	비면 일반 비교만 — Should-fix 보고
N (대안 개수)	선택	기본 3

wiki-doc-author

권위: .claude/agents/wiki-doc-author.md 의 ## Required Inputs. 요약:

입력	구분	누락 시 행동
mode (create | migrate)	필수	controller 에 reduction 요청
category	필수	NEEDS_CONTEXT
title	필수	NEEDS_CONTEXT
parent (daily-note·project-note 제외)	필수	추정 금지 — NEEDS_CONTEXT
file_slug	선택	title 에서 도출(create)
branch-note 의 sources[] + claim_evidence	필수(branch-note)	없으면 NEEDS_CONTEXT 또는 UNSUPPORTED_DECISION 라벨

명명된 실패 모드

• UNFILLED_REQUIRED_INPUT (C1): 필수 입력이 비었는데 자동조사·라벨 중 어느 것도 적용 안 됨.
• SILENT_GUESS (C1): 근거 없는 값을 추측해 FACT 로 채움 — 금지.
• MISSING_FALLBACK_ACTION (C2): 입력 누락에 대한 행동이 정의되지 않음.
• SSOT_DUPLICATION (C3): 입력 값을 agent 본문에서 참조하지 않고 본 계약에 복제 — drift 위험.
• UNBOUNDED_RESEARCH (/branch-spec): 자동조사가 bound 없이 확장.