구조화된 보고서 (Structured report)
네트워크 연결 없이 동작하는 단일 HTML 파일로, 바쁜 판독자가 다음을 수행할 수 있습니다:
- 전체 작업을 작업 맵으로 확인하고, 각 작업 내에서 대기 중인 사항을 파악합니다.
- 어떤 작업(및 그 안의 단계)이든 열어서 어떻게 수행되었는지, 각 주장이 왜 신뢰할 수 있는지 감사합니다.
- 보고서 내에서 바로 에이전트의 질문에 답변하고, 어떤 프롬프트가 어떤 결과를 생성했는지 확인합니다.
구조(Structure)와 내용(Content)
- 구조는 템플릿(
assets/template.html)에 속합니다: 레이아웃, 섹션 이름(Problem, Task, Context, Conclusions, Assumptions, Result, Not checked, Workflow, Needs approval, Your actions), 순서, 상태, 모든 아이콘 및 UI 레이블. 고정되어 있으며 항상 영어입니다. 아이콘은 구조만 표시하며 내용이 무엇인지는 표시하지 않습니다. - 내용은 사용자의 것입니다: 사용자 언어로 된 JSON입니다.
scripts/build.py가 이를 검증하고 템플릿의 플레이스홀더를 채웁니다. 직접 HTML을 작성하거나 섹션을 추가하지 않습니다.
워크플로우 (Workflow)
- 자료 수집: 메시지, 도구 결과, 파일, 명령어, 링크, 테스트, 측정값, 결정사항. 실제 발생한 내용만 보고합니다.
- 작업으로 분할 (1~12개): 하나의 작업 = 하나의 목표와 그 결과.
links로 연결:depends,blocks,related. - 각 작업 채우기 아래 규칙과
references/schema.md를 따릅니다. - JSON 작성 — 기본 경로는 작업 디렉터리의
reports/<YYYY-MM-DD>-<slug>.json입니다. - 빌드:
python3 <skill>/scripts/build.py <file>.json→<file>.html. 모든error:를 수정하고, 모든warning:을 읽고 진짜 경고가 아니라면 수정합니다. - 로컬에서 열기 (
open/xdg-open/start) 후 경로를 제공합니다. 절대 업로드하지 마십시오. - 채팅에서는 2~4줄로 요약 결과와 판독자에게 대기 중인 사항을 전달합니다.
살아있는 보고서: 세션 추적 및 답변 수신
사용자가 세션 동안 보고서를 최신 상태로 유지하기를 원하거나(추적/살아있는 보고서 요청) 다음 명령으로 세션을 한 번 바인딩합니다:
python3 <skill>/scripts/track.py start reports/<file>.json # <file>.journal.json 생성
그 후 UserPromptSubmit 훅(한 번 설치: track.py install-hook, Stop 훅도 함께 추가)은 모든 사용자 프롬프트를 저널에 기록하고 프롬프트 번호를 알려줍니다. 작업을 변경하는 각 프롬프트 후에 JSON을 업데이트하고 다시 빌드하십시오 — build.py는 모든 블록(각 노드 × 섹션)에 지문을 생성하고 새 블록이나 변경된 블록에 현재 프롬프트 번호를 스탬프합니다. 직접 스탬프를 작성하지 마십시오. 보고서에는 Prompts 레일이 표시되며, 프롬프트를 선택하면 해당 프롬프트에서 나타난(초록색) 또는 변경된(파란색) 내용이 강조됩니다.
판독자를 위한 질문. 결정사항을 approvals에 넣습니다. 각 항목은 질문과 옵션으로 구성됩니다 — 기본적으로 단일 선택(하나의 답변) 또는 "multi": true(해당하는 모든 옵션 선택 가능) — 사용자의 recommend(다중 선택의 경우 목록), why, due를 포함합니다. 판독자에게는 항상 "자신의 답변"이라는 추가 옵션이 제공됩니다. 옵션이 없는 질문은 자유 텍스트로 답변합니다. 보고서에서 Needs approval 섹션의 열린 질문은 시리즈를 형성하여 한 번에 하나씩 표시됩니다: 단일 선택 옵션은 답변과 함께 넘어가고, 다중 선택 또는 자신의 답변은 Next로 확인되며, 시리즈는 모든 답변 검토로 끝나고 Submit answers가 판독자의 답변을 보냅니다 — 다른 전송 방법은 없으며, actions(판독자가 수행하는 단계)에는 입력이 없습니다. 답변은 로컬 답변 서비스(127.0.0.1:47319, 빌드 시 시작 및 유지)로 전송되며, 일반 파일로 열린 보고서에서도 작동하고 저널에 다음 프롬프트로 저장됩니다. 보고서에 열린 질문이 있는 동안, 백그라운드 명령으로 대기 프로세스를 유지하십시오:
python3 <skill>/scripts/track.py wait reports/<file>.json
판독자가 답변을 보내면 wait가 답변을 출력하고 종료됩니다 — 이 출력이 다시 여러분에게 전달됩니다: 사용자의 프롬프트와 동일하게 처리하고 계속 진행하며, 남은 질문이 있으면 wait를 다시 시작합니다. 대기 프로세스가 실행 중이 아니라면, Stop 훅이 여러분의 차례가 끝나기 전에 대기 중인 답변을 전달하고, UserPromptSubmit 훅은 이를 사용자의 다음 메시지에 첨부합니다 — 답변이 손실되지 않습니다. 답변된 질문은 다음 빌드 후에 답변됨으로 표시됩니다. --static 플래그는 답변 채널 없이 보고서를 빌드합니다(이 머신 외부에서 공유용): 질문은 읽기 전용으로 표시되며 입력이 없습니다.
입력창 아래 링크. scripts/statusline.py는 세션 보고서의 상태 줄 하나를 출력합니다 — HTML을 브라우저에서 여는 클릭 가능한 링크와 남은 질문 수입니다. 상태 줄로 사용하거나 기존 상태 줄에 추가하십시오. 보고서가 없는 세션에서는 아무것도 출력하지 않습니다.
보고서의 모든 블록에는 Markdown으로 복사 버튼(전체 보고서, 작업 카드, 보고서, 섹션, 단일 항목, 단계, 프롬프트)이 있습니다 — 판독자가 다른 곳에 붙여넣기를 원할 때 이 버튼을 가리키십시오.
보고서를 신뢰할 수 있게 만드는 규칙
각 사항을 어떻게 알게 되었는지 분리하고, 절대 혼동하지 마십시오.
- context — 실제로 확인한 출처:
id(C1…), 짧은title, 실제url, 그리고 정확한 사실을 담은note. URL을 지어내지 마십시오. 저장소/웹 URL을 선호하십시오.file://링크는 판독자의 머신에서 열리지 않습니다(빌드에서 경고; 누락된 로컬 파일은 오류). - inferences — 결론, 각각
basis(컨텍스트 ID)와confidence포함. 근거(basis)가 없으면 가정(assumption)입니다. - assumptions — 확인 없이 참으로 가정한 사항:
why, 확인 방법(verify), 틀렸을 때의risk. - unchecked — 확인하지 않거나 수행하지 않은 사항과 그
why. 판독자는 이 부분을 다른 어떤 것보다 신뢰합니다; 솔직하게 말하십시오. 완료된 작업에unchecked가 없으면 경고가 표시됩니다 ([]는 "모든 것을 확인함"을 의미 — 실제로 그런 경우에만 사용). - result — 현재 존재하는 결과를 항목별로 나열. 모든
verified항목에는how가 필요합니다: 이를 증명하는 명령어, 테스트 또는 링크 — 이 정보가 없으면 빌드가 실패합니다. - stages — 실제로 수행한 단계, 레벨당 2~8개. 단계는 작업과 동일한 종류의 노드:
id+title필수, 모든 작업 필드 허용, 자체stages+flow로 깊이 제한 없음. 카드에는detail(무엇을 했는지),outcome(무엇이 나왔는지),status,when,uses가 표시됩니다. 단계를 클릭하면 동일한 구조로 보고서가 열리므로 실제 작업이 있었던 단계에는 실제 내용을 제공하십시오. 막다른 골목(failed/skipped)도 단계로 표시합니다. - next steps는 계획된 단계 — 아직 수행해야 할 작업은
status: "planned"인 단계로,detail(무엇을 할 것인지)과when(조건 또는 시간: "승인 후", "월요일")을 포함합니다. 계획된 또는 진행 중인 단계가 없는 미완료 작업은 경고가 표시됩니다. - approvals — 판독자만 결정할 수 있는 사항: 질문,
why(이 결정이 판독자의 몫인 이유),options(단일 선택 또는multi: true), 사용자의recommend(옵션 중 하나, 다중 선택의 경우 목록),due. 하나의 노드에 여러 관련 질문이 있으면 시리즈가 됩니다 — 판독자가 답변해야 할 순서대로 정렬하십시오. 이미 수행된 작업에 대해 승인을 요청하지 마십시오. - actions — 판독자만 수행할 수 있는 작업, 정확한
command와 관련된due포함. - secrets — 보고서는 전달됩니다. 키, 토큰, 개인 키, JWT, 비밀번호 할당 또는 URL 내 자격 증명으로 보이는 모든 것에서 빌드가 실패합니다(설치된 경우 gitleaks도 사용). 내용에서 제거하십시오. 수동으로 "마스킹"하지 마십시오. 로깅된 프롬프트의 시크릿은 자동으로 마스킹됩니다.
구조를 작성하고 산문을 피하십시오
모든 텍스트 필드는 구조를 렌더링하므로 구조를 제공하십시오:
- item→ 글머리 기호;1. item→ 번호 매기기(실제 순서만); 두 줄 이상의Key: value→ 정렬된 표; 문자열의 JSON 배열 → 글머리 기호.**bold**는 판독자가 반드시 알아야 할 한두 가지를 강조;==text==는 하이라이트;`code`는 식별자, 경로, 명령어.- 단락은 두 문장을 넘지 않음; 부제목이나 소개 줄 없음.
필드 지침: brief — 맵 카드용 1~3줄의 Key: value. problem — 키/값 사실. goal — 완료의 의미에 대한 글머리 기호. result.summary — 키/값 또는 글머리 기호.
언어
내용은 사용자 언어로, meta.lang은 해당 언어 코드로 설정합니다. 구조 레이블은 영어로 유지합니다.
파일
assets/template.html— 구조: 플레이스홀더, 스타일, 아이콘, 레이아웃, 탐색, 검색, 프롬프트 레일 및 응답을 위한 스크립트가 포함된 마크업.scripts/build.py— 내용 검증(위 규칙, 시크릿), 저널 스탬프, 템플릿 렌더링.--check는 검증만 수행;--template는 다른 템플릿 사용.scripts/track.py—start,wait,hook,stop-hook,daemon,status,install-hook(docstring 참조).scripts/statusline.py— Claude Code 상태 줄을 위한 보고서 링크.references/schema.md— 모든 필드.examples/— 영어 및 러시아어 예제; 러시아어 예제에는 5-프롬프트 저널이 포함되어 있습니다.