396 lines
19 KiB
YAML
396 lines
19 KiB
YAML
report-templates:
|
|
version: 1
|
|
provenance: "직무별 보고서 템플릿 및 소통 체계.md (추출 후 원문 삭제 예정)"
|
|
purpose: 75개 concrete AI 역할이 작업 후 상급자에게 올리는 표준 보고서 템플릿을 기계가 읽을 스키마로 흡수한다.
|
|
cross-references:
|
|
- "org-os/06-agent-work/collaboration-modes.yaml (report-header BLUF)"
|
|
- "org-os/06-agent-work/context-package-spec.yaml (expected-output.report-header)"
|
|
- "org-os/00-role-registry/drai-matrix.yaml (문서유형별 Decider/Recommender/Auditor/Informed)"
|
|
|
|
# 2단 보고: YAML(에이전트끼리, SoT) → render_report.py → MD(대표용, 가독성)
|
|
human-md-rendering:
|
|
principle: 에이전트는 .report.yaml만 쓴다(SoT, hook 검증). 대표용 MD는 render_report.py가 결정적으로 생성한다(손으로 안 씀 → drift 없음).
|
|
renderer: .claude/hooks/render_report.py
|
|
output: 같은 basename .md + reports/INDEX.md(목차 자동)
|
|
md-sections: [결론(BLUF 콜아웃), 결정 필요, 확신도, 결정 질문, 권고안, "역할별 핵심 결론(요약 표)", "역할별 상세(관점 원문 embed — findings/설계/지표/다음액션)", 합의/충돌, 리스크, 근거 표, 원본 YAML 링크]
|
|
self-contained: true # 사람이 MD 하나만 읽으면 되도록 본문 상세를 embed(링크로 떠넘기지 않음)
|
|
type-map: # render_report.py --type
|
|
decision: ExecutiveDecisionPacket / DecisionBrief
|
|
completion: CompletionRecord
|
|
work: AIWorkReport
|
|
review: ReleaseAcceptance / LearningReview
|
|
blocked: BlockedReport
|
|
design: "RFC/ADR / overall-design"
|
|
# finding #13: render_report.py 는 이 배지를 **읽어서** MD 제목 아이콘/라벨을 정한다
|
|
# (예전엔 코드에 TYPE_BADGE 하드코딩 → SSOT 미소비). 이 YAML을 고치면 렌더 결과가 바뀐다.
|
|
# 파일 부재/파싱 실패 시 render_report 내장 기본값으로 폴백(하드페일 없음).
|
|
render-badges: # render_report.py --type <T> -> [emoji, label]
|
|
decision: ["🟢", "결정"]
|
|
work: ["📝", "작업"]
|
|
completion: ["✅", "완료"]
|
|
review: ["🔍", "리뷰"]
|
|
blocked: ["🚨", "블로커"]
|
|
design: ["📐", "설계"]
|
|
spec: ["📋", "명세"]
|
|
fan-out-aggregation: render_report.py <synthesis.report.yaml> --members <role1.report.yaml> <role2.report.yaml> … → "역할별 핵심 결론" 표로 집계
|
|
|
|
# Slack 결과보고 규약(기본). ~/.claude 템플릿 3(agent-report)을 사용.
|
|
slack-reporting:
|
|
template: "~/.claude/CLAUDE.md 템플릿 3 — agent-report(BLUF·SBAR·STAR·DACI 합성)"
|
|
thread-convention: >
|
|
fan-out wave는 부모=종합 결정 1건 + 각 워커의 개별 agent-report를 그 부모의 스레드 답글로 붙인다
|
|
(slack_reply_to_thread). 누가 무엇을 판단했는지 다 보이되 채널 스팸은 없다. collapse wave는 부모 1건만.
|
|
scope: blocker/human-review/critical/digest는 자동(notify_slack), fan-out 결과는 스레드 단위로.
|
|
tools: ".claude/hooks/notify_slack.py report + mcp__slack__slack_reply_to_thread"
|
|
|
|
# 정책: 모든 보고서는 answer-first(BLUF). report-header가 항상 문서 최상단.
|
|
# 원문이 과정-우선 순서로 서술한 템플릿은 answer-first 순서로 재배열해 반영했다.
|
|
answer-first-policy:
|
|
rule: 모든 상위 보고서는 결론을 맨 앞에 둔다. report-header(BLUF)를 최상단에 배치하고 그 뒤에 근거·과정을 둔다.
|
|
enforced-by: "must-lead-with: report-header (각 템플릿 필드) + ceo-intake Stop hook 검증"
|
|
rationale: 상급자와 사용자가 30초 안에 결론·권고·결정 필요 여부를 판단할 수 있어야 한다.
|
|
|
|
# 모든 보고서 최상단 필수 헤더(BLUF). context-package-spec expected-output.report-header와 정합.
|
|
common-report-header:
|
|
- bottom-line
|
|
- "decision-needed(needed, approver)"
|
|
- "confidence(value, derived-from)"
|
|
- risks
|
|
- evidence
|
|
structured-projection:
|
|
version: 1
|
|
purpose: bounded synthesis와 tiered rehydration을 위한 표준 읽기 표면
|
|
required-fields: [decision-summary, evidence-index, dissent, open-risks, artifact-refs]
|
|
expansion-policy:
|
|
light: projection-only
|
|
standard: projection-first; full report only on conflict, dissent, low-confidence, critical-claim, reviewer-request
|
|
heavy: full-report
|
|
report-header-schema:
|
|
bottom-line: 한 문장 결론 또는 권고
|
|
decision-needed:
|
|
needed: "true / false"
|
|
approver: 사람(HUMAN-001) 또는 EXEC-CEO 등 결정권 역할
|
|
confidence:
|
|
value: "High / Med / Low"
|
|
derived-from: evidence
|
|
risks: []
|
|
evidence:
|
|
- source-uri: 실존 파일 경로 또는 근거 URI
|
|
grade: "E0 / E1 / E2 / E3 / E4 / E5"
|
|
report-header-rules:
|
|
- report-header 없이 보고서를 종료하지 않는다.
|
|
- evidence 없는 confidence High 는 금지한다.
|
|
- confidence Low 보고서는 단독 승인·실행하지 않는다.
|
|
- "decision-needed.needed=true 이면 approver 를 반드시 명시한다."
|
|
|
|
method-execution-contract:
|
|
applies-to: active Contract v2 role의 standard/heavy 산출물
|
|
current-checkpoint-rule: >
|
|
지금 제출하는 required-output step은 artifact-refs로 자기 SHA를 적지 않고
|
|
output-binding: current-artifact로 바인딩한다. 그 이전 output step만 trusted artifact의
|
|
report-id+sha256을 artifact-refs로 참조하며, 미래 step 결과는 기록하지 않는다.
|
|
example:
|
|
role-id: ENG-BE
|
|
method-id: backend-implementation
|
|
contract-sha256: "<active-contract-sha256>"
|
|
step-results:
|
|
- step-id: design-api
|
|
status: completed
|
|
output-binding: trusted-artifact
|
|
artifact-refs: [{ report-id: api-v1, sha256: "<exact-sha256>" }]
|
|
- step-id: implement-verify
|
|
status: completed
|
|
output-binding: current-artifact
|
|
self-check-results:
|
|
- { step-id: implement-verify, gate-id: contract-verified, verdict: Passed, evidence-refs: ["<receipt-id>"] }
|
|
independent-judgment-rule: >
|
|
reviewer-role이 producer와 다르면 대상 artifact를 먼저 Submitted로 등록하고,
|
|
reviewer가 exact id+sha에 결속된 method-judgment-review를 제출한 뒤에만 원본을 Accepted 처리한다.
|
|
|
|
# 근거 등급(원문 7.4). report-header.evidence[].grade 및 근거 품질 평가에 공통 사용.
|
|
evidence-grades:
|
|
E0: 근거 없는 주장 — 결정 근거 사용 금지
|
|
E1: AI 추론·가정·경험칙 — assumptions 로만 사용
|
|
E2: 외부 사례·경쟁사·일반 시장 자료(raw) — 참고 근거
|
|
E3: 내부 문서·기존 결정·회고·고객 상담 기록 — 강한 근거
|
|
# finding #20(외부자료 E2/E3 혼용 해소): 원출처가 외부라도 **하네스 표준으로 채택된 방법론**
|
|
# (skill '근거' 섹션: Refactoring UI·C4·Diátaxis·12-Factor 등)은 '채택 결정'이 있으므로 E3로 본다.
|
|
# 아직 채택 안 된 raw 외부 시장/경쟁 자료는 E2. 즉 등급 차이는 '채택 여부'로 갈린다(출처 국적 아님).
|
|
E4: 내부 지표·로그·행동 데이터·재무 데이터 — 매우 강한 근거
|
|
E5: 실험·운영 검증·테스트 결과·배포 후 계측 — 핵심 결정 근거
|
|
rule: High 이상 리스크 결정은 E4/E5 근거 없이 자동 승인하지 않는다. C-Level 권고는 최소 하나의 E3 이상 근거가 필요하다.
|
|
|
|
templates:
|
|
# 1) 직무 AI 표준 작업 보고서 (원문 2.8 AI Work Report). 상위 AI 검토용.
|
|
- id: AIWorkReport
|
|
drai-document-type: "LearningReview (parent-review 계열)"
|
|
audience: parent-role-agent
|
|
decider: parent-role-agent
|
|
must-lead-with: report-header
|
|
# answer-first 재배열: 원문(직무관점→입력→핵심판단→...)을 결론 우선으로 재정렬.
|
|
answer-first-note: 원문은 직무 관점부터 서술하나, 핵심 판단·결정 필요를 상단으로 올려 재배열.
|
|
sections:
|
|
- 핵심 판단
|
|
- 결정 필요 사항
|
|
- 판단 근거
|
|
- 가정과 반대 가능성
|
|
- 직무 관점
|
|
- 입력 요약
|
|
- 다음 액션과 핸드오프
|
|
required-fields:
|
|
- task-id
|
|
- role-agent
|
|
- role-perspective
|
|
- team-type
|
|
- input-documents
|
|
- output-artifacts
|
|
- status
|
|
- confidence
|
|
- assumptions
|
|
- "handoff-to(role-agent, expected-output)"
|
|
- human-review-needed
|
|
enums:
|
|
status: "Draft / Review / Approved / Blocked / Closed"
|
|
confidence: "High / Med / Low" # 정본 enum(validate_report 강제): High/Med/Low. severity 는 별개(Low/Medium/High/Critical).
|
|
quality-gate: 입력 문서·핵심 판단·근거·가정·신뢰도·handoff-to 필수. 미충족 시 Changes Requested.
|
|
rules:
|
|
- handoff-to 가 비면 다음 실행으로 이어지지 않는 종료형으로 본다.
|
|
- 여러 AIWorkReport 가 모이면 6-Pager/PR-FAQ/RFC-ADR 등 정식 문서로 승격할 수 있다.
|
|
|
|
# 2) 상위 통합 의사결정 문서 (원문 7.6). drai-matrix: ExecutiveDecisionPacket.
|
|
- id: ExecutiveDecisionPacket
|
|
drai-document-type: ExecutiveDecisionPacket
|
|
audience: [EXEC-CEO, HUMAN-001]
|
|
decider: [EXEC-CEO, HUMAN-001]
|
|
recommender: [EXEC-CTO, EXEC-CPO, EXEC-CFO, EXEC-COO, EXEC-CPTO]
|
|
auditor: [OPS-ORCH, ARCH-SWAT]
|
|
must-lead-with: report-header
|
|
# answer-first: 권고를 최상단(30초 판단). 원문 1~9 순서를 권고·사용자결정 우선으로 재배열.
|
|
answer-first-note: 원문은 결정 질문부터 대안·권고 순서이나, 권고안과 사용자 결정 항목을 상단으로 재배열.
|
|
sections:
|
|
- 결정해야 할 질문
|
|
- 권고안
|
|
- CEO 또는 사용자 결정 필요 항목
|
|
- 역할별 핵심 결론
|
|
- 합의된 내용
|
|
- 충돌하는 내용
|
|
- 근거 품질 평가
|
|
- 선택 가능한 대안
|
|
- 하위 팀 전달 지시
|
|
required-fields:
|
|
- decision-id
|
|
- source-brief
|
|
- authoring-agent
|
|
- "participating-roles(CTO/CPO/CFO/COO/CPTO)"
|
|
- status
|
|
- human-review-needed
|
|
- linked-reports
|
|
- selected-option-id
|
|
- evaluation-criteria
|
|
- option-evaluations
|
|
- tradeoffs
|
|
- dissent
|
|
- kill-criteria
|
|
- revisit-conditions
|
|
- evidence-refs
|
|
enums:
|
|
status: "Draft / Review / Approved / Blocked / Closed"
|
|
quality-gate: 역할별 결론·합의/충돌·근거 등급·대안·CEO 권고·사용자 결정 항목 필수. 미충족 시 Escalated.
|
|
rules:
|
|
- C-Level 개별 보고서 링크를 linked-reports 에 모두 연결한다.
|
|
- 합의된 내용과 충돌하는 내용을 모두 보존한다(이견 삭제 금지).
|
|
- 근거 품질 평가 없는 권고안은 Review 를 넘길 수 없다.
|
|
- human-review-needed true 이면 사용자 승인 없이 하위 팀 실행으로 넘기지 않는다.
|
|
- 하위 팀에는 C-Level 개별 의견이 아니라 승인된 Packet 을 입력으로 전달한다.
|
|
|
|
# 3) 작업 완료 기록 (원문 6.7.2 completion-record). 상위 AI acceptance-decision 입력.
|
|
- id: CompletionRecord
|
|
drai-document-type: "completion-record (parent-review 대상)"
|
|
audience: parent-role-agent
|
|
decider: parent-role-agent
|
|
must-lead-with: report-header
|
|
answer-first-note: work-summary 결론을 bottom-line 으로 상단화하고 산출물·검증·리스크를 뒤에 둔다.
|
|
sections:
|
|
- 작업 요약
|
|
- 산출물
|
|
- 사용 근거
|
|
- 검증 결과
|
|
- 남은 리스크
|
|
- 핸드오프
|
|
required-fields:
|
|
- completion-id
|
|
- source-request-id
|
|
- completed-by
|
|
- completed-team
|
|
- work-summary
|
|
- "output-artifacts(type, uri)"
|
|
- evidence-used
|
|
- "verification-performed(check, result)"
|
|
- remaining-risks
|
|
- "handoff-to(role-agent, reason, expected-next-output)"
|
|
- status
|
|
enums:
|
|
status: "Submitted-for-Review / Accepted / Changes-Requested / Blocked / Escalated"
|
|
quality-gate: 산출물 링크·검증 결과·남은 리스크·handoff-to 필수. 미충족 시 Changes Requested.
|
|
rules:
|
|
- 상위 AI 의 acceptance-decision 없이는 Closed 가 될 수 없고 Submitted-for-Review 로 남는다.
|
|
- handoff-to 가 비면 종료형 산출물이어야 하며 그 이유를 적는다.
|
|
- 다음 AI 직무가 필요하면 expected-next-output 을 반드시 쓴다.
|
|
|
|
# 4) 작업 중단 보고서 (원문 2.9). drai-matrix: BlockedReport.
|
|
- id: BlockedReport
|
|
drai-document-type: BlockedReport
|
|
audience: [OPS-ORCH, EXEC-CEO, HUMAN-001]
|
|
decider: [OPS-ORCH]
|
|
recommender: [worker-role-agent, parent-role-agent]
|
|
auditor: [QA, ARCH-SWAT]
|
|
informed: [EXEC-CEO, HUMAN-001]
|
|
must-lead-with: report-header
|
|
answer-first-note: 무엇이 왜 막혔고 누가 풀어야 하는지를 bottom-line 으로 상단화한다.
|
|
sections:
|
|
- 문제 요약
|
|
- 영향
|
|
- 근거
|
|
- 필요한 검토 역할
|
|
- 해결 경로
|
|
- 재개 조건
|
|
required-fields:
|
|
- blocker-id
|
|
- detected-by
|
|
- detected-team
|
|
- blocked-task
|
|
- blocker-type
|
|
- severity
|
|
- status
|
|
- "source-documents(title, uri, relevant-section)"
|
|
- problem-summary
|
|
- "evidence(finding, uri)"
|
|
- impact
|
|
- "required-review-roles(role-agent, reason)"
|
|
- suggested-resolution-path
|
|
- resume-condition
|
|
- slack-notification-needed
|
|
- human-review-needed
|
|
enums:
|
|
blocker-type: "design-inconsistency / missing-decision / implementation-impossible / test-failure-from-design / security-blocker / reliability-blocker / data-contract-conflict"
|
|
severity: "Low / Medium / High / Critical"
|
|
status: Blocked
|
|
quality-gate: blocker 유형·영향·근거·필요 검토 역할·resume-condition 필수. 미충족 시 Escalated.
|
|
rules:
|
|
- 구현 AI 는 설계 충돌 발견 시 임시 우회 구현 대신 BlockedReport 를 먼저 작성한다.
|
|
- required-review-roles 에 원인 역할과 검토 역할을 모두 적는다.
|
|
- severity High 이상이면 slack-notification-needed 와 human-review-needed 기본값 true.
|
|
- resume-condition 충족 전까지 해당 작업을 재개하지 않는다.
|
|
|
|
# 5) CEO 인테이크 산출물 (원문 1.7 / .claude/commands/ceo-intake.md).
|
|
- id: DecisionBrief
|
|
drai-document-type: "none (CEO 인테이크 산출물, User Intake 단계)"
|
|
audience: [HUMAN-001, OPS-ORCH, EXEC-CEO]
|
|
authored-by: EXEC-CEO
|
|
must-lead-with: report-header
|
|
answer-first-note: 사용자 의도 재진술 뒤 report-header(BLUF)로 시작. mode/tier/candidate-families 를 선언.
|
|
sections:
|
|
- 사용자 의도 재진술
|
|
- 결정 질문
|
|
- 목표와 성공 기준
|
|
- mode 선언
|
|
- tier 제안
|
|
- 후보 capability-family
|
|
required-fields:
|
|
- report-header
|
|
- mode
|
|
- tier
|
|
- candidate-families
|
|
enums:
|
|
mode: "divergent / converge"
|
|
tier: "light / standard / heavy"
|
|
quality-gate: report-header 없이 종료 금지. evidence 없는 confidence High 금지. candidate family는 전부 등록·고유·non-empty이고 tier 렌즈 바닥을 이론적으로 커버해야 한다.
|
|
rules:
|
|
- CEO AI 는 사용자 요청을 바로 실행 지시로 바꾸지 않고 결정 질문과 성공 기준을 먼저 정리한다.
|
|
- mode 불명확 시 converge, production/customer/revenue 접촉이면 독립 tier-check 필요.
|
|
- workflow queue/state 직접 조작 금지(Orchestrator 담당), 사용자 최종 승인 대체 금지.
|
|
|
|
# 6) 기술 결정 기록 (원문 2.3). drai-matrix: RFC/ADR.
|
|
- id: "RFC/ADR"
|
|
drai-document-type: "RFC/ADR"
|
|
audience: [EXEC-CTO]
|
|
decider: [EXEC-CTO]
|
|
recommender: [ARCH-SOLUTION, ARCH-APP, ARCH-TECH, ARCH-DATA, SRE, SEC-APPSEC]
|
|
auditor: [SEC-ENGINEER, QA, ARCH-SWAT]
|
|
informed: [ENG-BE, ENG-FE, INFRA-PLATFORM, DATA-ENGINEER]
|
|
must-lead-with: report-header
|
|
# answer-first: report-header(제안 결정 BLUF)를 최상단에 두고 본문은 RFC 논리 구조 유지.
|
|
answer-first-note: report-header 에 제안 결정을 BLUF 로 요약. 본문은 Proposed Design(결정)을 Context 앞으로 올려 재배열.
|
|
sections:
|
|
- Proposed Design
|
|
- Context
|
|
- Alternatives Considered
|
|
- "Security / Privacy / Compliance"
|
|
- "Consequences & Trajectory"
|
|
- Fitness Functions
|
|
required-fields:
|
|
- rfc-adr-id
|
|
- author
|
|
- co-authors
|
|
- tech-approver
|
|
- status
|
|
- effective-date
|
|
- related-docs
|
|
- context
|
|
- proposed-design
|
|
- alternatives-considered
|
|
- security-privacy-compliance
|
|
- consequences-trajectory
|
|
- fitness-functions
|
|
enums:
|
|
status: "Proposed / Accepted / Deprecated / Superseded"
|
|
quality-gate: Context·Proposed Design·Alternatives·Security·Consequences·Fitness Functions 필수. 미충족 시 Blocked.
|
|
rules:
|
|
- 결정 이유와 기각한 대안을 반드시 남긴다.
|
|
- EA 5계층(Business/Data/Application/Technology/Security) 검토 렌즈를 적용한다.
|
|
- 제목은 현재형 명령문으로 쓴다.
|
|
|
|
# 7) 최종 릴리스 수용 (원문 1.22). drai-matrix: ReleaseAcceptance.
|
|
- id: ReleaseAcceptance
|
|
drai-document-type: ReleaseAcceptance
|
|
audience: [EXEC-CEO, HUMAN-001]
|
|
decider: [EXEC-CEO, HUMAN-001]
|
|
recommender: [EXEC-VPENG, PROD-PO, QA, SRE, SEC-APPSEC]
|
|
auditor: [OPS-ORCH, SEC-ENGINEER]
|
|
informed: [EXEC-CTO, EXEC-CPO, EXEC-CFO, EXEC-COO]
|
|
must-lead-with: report-header
|
|
answer-first-note: final-status 와 미해결 리스크·사용자 결정 필요 여부를 bottom-line 으로 상단화한다.
|
|
sections:
|
|
- 최종 상태
|
|
- 승인 요건
|
|
- 검증 기록
|
|
- 미해결 리스크
|
|
- 사용자 결정 상태
|
|
- Fit 체크리스트
|
|
required-fields:
|
|
- release-id
|
|
- workflow-id
|
|
- scope
|
|
- "required-approvals(role-agent, status)"
|
|
- verification-records
|
|
- "unresolved-risks(risk, owner)"
|
|
- user-decision-status
|
|
- final-status
|
|
enums:
|
|
final-status: "Approved / Changes-Requested / Blocked / Stopped"
|
|
fit-checklist:
|
|
- "Product Fit: PR/FAQ 또는 제품 목표와 구현 결과 일치"
|
|
- "Technical Fit: RFC/ADR 와 실제 구현 일치"
|
|
- "Quality Fit: 테스트·QA 검증·미검증 영역 공개"
|
|
- "Security Fit: AppSec/보안 체크 완료"
|
|
- "Reliability Fit: SRE/SLO 영향 확인"
|
|
- "Data Fit: 계측·데이터 모델·분석 가능성 확인"
|
|
- "Operations Fit: 운영/지원 흐름과 예외 처리 확인"
|
|
- "Financial Fit: 비용/ROI 제약 위반 없음"
|
|
- "User Decision Fit: 사용자 승인 또는 수정 지시 반영"
|
|
quality-gate: 필수 승인·검증 기록·미해결 리스크·사용자 결정 상태 필수.
|
|
rules:
|
|
- final-status Approved 전에는 전체 workflow 를 Closed 로 표시하지 않는다.
|
|
- unresolved-risk 는 owner 와 후속 조치를 남긴다.
|
|
- 사용자 결정이 필요한 release 는 CEO AI 권고안 정리 후 사용자 승인 없이 완료하지 않는다.
|