From 0501f30a27797286218bad69c3e3e9f4d0346c6d Mon Sep 17 00:00:00 2001 From: DongHun Date: Sat, 3 Oct 2026 00:17:23 +0900 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=EB=B3=B4=EA=B3=A0=EC=84=9C=20?= =?UTF-8?q?=ED=85=9C=ED=94=8C=EB=A6=BF=20v0.1=EA=B3=BC=20=EC=82=AC?= =?UTF-8?q?=EB=A1=80=EB=B3=84=20=EA=B8=B0=EB=8C=80=20=EC=B6=9C=EB=A0=A5?= =?UTF-8?q?=EC=9D=84=20=EC=A0=95=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../report-template-discussion-2026-09-22.md | 4 +- docs/design/report-template-v0.1-examples.md | 539 ++++++++++++++++++ docs/design/report-template-v0.1.md | 266 +++++++++ 3 files changed, 808 insertions(+), 1 deletion(-) create mode 100644 docs/design/report-template-v0.1-examples.md create mode 100644 docs/design/report-template-v0.1.md diff --git a/docs/design/report-template-discussion-2026-09-22.md b/docs/design/report-template-discussion-2026-09-22.md index 8cce089..0f55b5e 100644 --- a/docs/design/report-template-discussion-2026-09-22.md +++ b/docs/design/report-template-discussion-2026-09-22.md @@ -6,6 +6,8 @@ 상태: 기본 방향 합의 · 사례와 세부 표현 검토안 범위: 이 작업 전용 제안 문서. 공통 PRD 및 제품 코드의 정본 계약을 대체하지 않는다. +2026-10-02 후속 설계: [보고서 템플릿 v0.1](report-template-v0.1.md)과 [네 대표 사례의 기대 출력](report-template-v0.1-examples.md)을 참고한다. 아래는 2026-09-22 당시 논의이며, 최신 MVP와의 입력 차이·남은 계약 결정은 후속 설계에 정리했다. + ## 읽기 순서 - [합의한 기본 방향](#합의한-기본-방향) @@ -276,4 +278,4 @@ - Discord에서도 각 사례의 핵심 발견과 중요한 한계 보존 - 생산자 실패·종료 계약 또는 모델 출력 범위의 확정·변경 지시 0건 -이는 템플릿 검토 기준이며 실행한 제품 테스트 결과가 아니다. 공통 PRD·제품 파일 수정, 제공자 호출, 실제 진단, 저장·전달 검증은 이 문서 작성에 포함되지 않는다. \ No newline at end of file +이는 템플릿 검토 기준이며 실행한 제품 테스트 결과가 아니다. 공통 PRD·제품 파일 수정, 제공자 호출, 실제 진단, 저장·전달 검증은 이 문서 작성에 포함되지 않는다. diff --git a/docs/design/report-template-v0.1-examples.md b/docs/design/report-template-v0.1-examples.md new file mode 100644 index 0000000..520be29 --- /dev/null +++ b/docs/design/report-template-v0.1-examples.md @@ -0,0 +1,539 @@ +# 보고서 템플릿 v0.1: 대표 사례별 기대 출력 + +빈 결과·시간 초과·관측 불일치·결과 잘림의 합성 사례로 상세 7구획과 Discord 기대 문구를 비교한다. 정제 근거가 필요한 목표 출력과 현재 입력으로 가능한 표현을 구분하며, 제품 실행 결과로 취급하지 않는다. + +작성일: 2026-10-02 · 상태: 합의된 v0.1 구조의 합성 기대 출력 + +구조 합의의 범위와 테스트에 따른 개선 원칙은 [템플릿 v0.1](report-template-v0.1.md#v01-구조-합의와-개선-원칙)을 따른다. 이 자료는 후속 테스트의 비교 기준이며 사례별 의미 검토와 제품 검증 완료를 뜻하지 않는다. + +읽기 순서: + +1. [템플릿·입력·책임](report-template-v0.1.md) +2. [사례 A: 성공 → 성공 → 빈 결과](#사례-a-성공성공빈-결과) +3. [사례 B: 성공 → 성공 → 시간 초과](#사례-b-성공성공시간-초과) +4. [사례 C: 관측 불일치와 근거 부족](#사례-c-관측-불일치와-근거-부족) +5. [사례 D: 결과 잘림](#사례-d-결과-잘림) +6. [검증 기록](#검증-기록) + +## 공통 전제와 표기 + +모든 시각·연결 번호·대상은 합성이다. 실제 AMDB 기록, 실행된 도구 출력, 현재 스키마에 맞는 JSON fixture가 아니다. 아래 입력표의 잠금 관계는 후속 정규화 계약이 제공해야 할 **의미 수준의 허용 사실 후보**를 사람이 적은 것이다. 원시 SQL 행을 전달한 것이 아니며 이 문서가 해당 값을 모델·보고서에 보내도록 승인하지 않는다. + +네 목표 보고서는 전용 정규화기가 사실·대상·시각·참조·크기를 검증했다는 조건부 기대 출력이다. + +현재 MVP에 그 사실 입력이 없으므로 그대로 생성할 수 없다. 각 사례 끝의 “현재 입력만 있을 때”는 같은 자료에서 현재 코드가 보존하는 메타데이터만으로 쓸 수 있는 표현이다. 이 표현도 현재 포매터가 실제 생성한 문자열을 캡처한 것은 아니다. + +표시용 `call-N`은 각 사례의 진단 ID에 속한 정확한 `:call-N`의 약칭이다. 사례 간 ID를 연결하지 않는다. 숫자를 `tc_`/`ev_`로 바꾸지 않는다. 제품 표시에서는 저장된 전체 ID와의 대응을 보존해야 한다. + +- A 진단 ID: `diag-00000000-0000-4000-8000-00000000000a` +- B 진단 ID: `diag-00000000-0000-4000-8000-00000000000b` +- C 진단 ID: `diag-00000000-0000-4000-8000-00000000000c` +- D 진단 ID: `diag-00000000-0000-4000-8000-00000000000d` + +공통 사례 전제: 합성 대상 별칭은 `sample-db`, 도구는 `mysql_get_lock_waits`, 검토 목적은 요청된 지연과 잠금 대기의 관련성 확인이다. 대상 별칭·검토 목적도 현재 Report 투영에는 없다. 시간은 모두 2026-09-18 UTC의 호출 기록 시각이며 측정 구간·연속 관측을 뜻하지 않는다. + +실제 요청 지연, 요청-연결 대응, 필터·전체 검사 범위, 트랜잭션 동일성·상태는 제공하지 않는다. 아래 “미제공” 판단은 이 사례 전제에 근거한다. + +--- + +## 사례 A: 성공→성공→빈 결과 + +합성 입력: `completion_reason=investigation_complete`. 종료 이유만으로 필요한 검사를 모두 마쳤다고 판단하지 않는다. + +| 호출 | 기록 시각 | 실행 기록 | 조건부 정제 관측 | +|---|---|---|---| +| call-1 | 10:00:00 | success, 반환 1행, 잘림 false | 연결 386이 382의 잠금 해제를 기다리는 관계 | +| call-2 | 10:01:00 | success, 반환 1행, 잘림 false | 연결 386이 382의 잠금 해제를 기다리는 관계 | +| call-3 | 10:02:00 | success, 반환 0행, 잘림 false | 이번 조회의 반환 행 없음 | + +### 1. 진단 요약 + +앞선 두 조회에 연결 386이 382의 잠금 해제를 기다리는 관계가 기록됐습니다. [call-1, call-2] + +마지막 조회의 반환 행은 0건입니다. [call-3] + +잠금 대기가 지연에 영향을 주었을 가능성은 있으나 원인은 미확정이며, 빈 결과만으로 증상 해소를 확인할 수 없습니다. + +--- + +### 2. 조사 대상·범위 + +사례 전제의 sample-db 지연 관련 자료로, 10:00·10:01·10:02 UTC의 잠금 대기 조회 3건을 검토했습니다. [call-1, call-2, call-3] + +각 호출의 반환 결과만 다룹니다. 측정 구간·필터·실제 지연값과 필수 검사 충족 여부는 미제공입니다. + +종료 이유는 진단 에이전트의 조사 종료입니다. + +--- + +### 3. 확인된 사실 + +| 종류 | 사실 | 호출 근거 | +|---|---|---| +| 원천 관측 | 10:00 기록에 연결 386→382의 잠금 대기 관계가 있습니다. | call-1 | +| 원천 관측 | 10:01 기록에도 같은 연결 번호의 대기 관계가 있습니다. | call-2 | +| 실행 기록 | 10:02 조회는 성공했고 반환 행은 0건이며 잘림 표식은 false입니다. | call-3 | + +--- + +### 4. 원인 가설과 근거 + +가능성: 관측된 잠금 대기가 요청된 지연에 영향을 주었을 수 있습니다. [call-1, call-2] + +요청과 연결 번호의 대응이 없어 인과관계는 확인되지 않았습니다. 마지막 빈 결과는 앞선 관측을 지우거나 복구를 증명하지 않습니다. [call-3] + +--- + +### 5. 조사 한계·조회 실패 + +제공된 세 기록은 모두 성공이며 잘림 표식은 false입니다. [call-1, call-2, call-3] + +다만 연속 관측이 아니므로 대기가 2분 지속됐다고 말할 수 없습니다. 같은 연결 번호가 같은 트랜잭션임을 뜻하지 않습니다. 지연 측정값과 전체 검사 범위가 없고, 마지막 0행으로 전체 정상·복구를 판단할 수 없습니다. [call-3] + +--- + +### 6. 후속 확인 사항 + +| 확인 항목 | 목적 | +|---|---| +| 지연이 발생한 시각과 요청-연결 대응 | 앞선 대기 관계와 증상의 관련성을 확인합니다. | +| 해당 시점의 트랜잭션 정보 | 연결 382가 잠금을 유지한 이유를 좁힙니다. | +| 현재 증상과 후속 관측의 확인 가능 여부 | 마지막 빈 결과 이후 증상이 남아 있는지 검토합니다. | + +담당자의 확인 항목이며 자동 실행 지시가 아닙니다. + +--- + +### 7. 호출별 상세 근거 + +| 호출 ID 약칭 | 도구 | 기록 시각 | 허용된 결과 요약 | +|---|---|---|---| +| call-1 | mysql_get_lock_waits | 10:00:00 | 성공, 1행, 386→382 대기 관계, 잘림 false | +| call-2 | mysql_get_lock_waits | 10:01:00 | 성공, 1행, 386→382 대기 관계, 잘림 false | +| call-3 | mysql_get_lock_waits | 10:02:00 | 성공, 0행, 잘림 false. 전체 범위의 대기 부재를 증명하지 않음 | + +--- + +### Discord 기대 출력 + +> **합성 예시 · 잠금 대기 조사 / 원인 미확정** +> +> **진단 ID:** diag-00000000-0000-4000-8000-00000000000a +> +> **조사 종료:** 진단 에이전트 조사 종료 · 호출 3건, 성공 3건, 실패 0건 +> +> 두 조회에 386→382 대기 관계가 있습니다. [call-1, call-2] +> +> 마지막은 반환 0행입니다. [call-3] 지연과의 관련성·증상 해소는 미확인입니다. 전체 검사 범위도 확인되지 않았습니다. +> +> **후속 확인:** 지연 시각·요청-연결 대응과 당시 트랜잭션 정보 +> +> **상세:** amdc-report.md · 개별 호출 상세 3건은 첨부 참조 + +--- + +### 현재 입력만 있을 때 + +> 첫 두 조회는 각각 1행, 마지막 조회는 0행을 반환했고 잘림 표식은 없습니다. [call-1, call-2, call-3] +> +> 잠금 관계의 구체적 내용과 지연 관련성은 확인할 수 없습니다. 원인·증상 해소는 미확정입니다. + +연결 386/382를 사실로 쓰지 않고 가설도 근거가 없으면 보류합니다. + +--- + +## 사례 B: 성공→성공→시간 초과 + +합성 입력: `completion_reason=insufficient_evidence`. 마지막 오류는 `tool_timeout`, 결과는 미확보입니다. + +| 호출 | 기록 시각 | 실행 기록 | 조건부 정제 관측 | +|---|---|---|---| +| call-1 | 10:00:00 | success, 반환 1행, 잘림 false | 연결 386이 382의 잠금 해제를 기다리는 관계 | +| call-2 | 10:01:00 | success, 반환 1행, 잘림 false | 연결 386이 382의 잠금 해제를 기다리는 관계 | +| call-3 | 10:02:00 | error, tool_timeout, 결과 미확보 | 없음. 0행으로 대체하지 않음 | + +### 1. 진단 요약 + +성공한 두 조회에 연결 386→382의 잠금 대기가 기록됐습니다. [call-1, call-2] + +마지막 조회는 시간 초과로 결과를 얻지 못했습니다. [call-3] + +지연 원인은 미확정이며 대기의 후속 상태와 증상 해소 여부도 알 수 없습니다. + +--- + +### 2. 조사 대상·범위 + +사례 전제의 sample-db 잠금 대기 조회 3건 중 두 호출에서 결과를 얻었습니다. [call-1, call-2, call-3] + +10:02는 실패 기록 시각이며 성공한 측정 시각이 아닙니다. [call-3] + +종료 이유는 판단 근거 부족입니다. + +실제 지연값·요청 대응·필터와 전체 검사 범위는 미제공입니다. + +--- + +### 3. 확인된 사실 + +| 종류 | 사실 | 호출 근거 | +|---|---|---| +| 원천 관측 | 10:00 기록에 연결 386→382의 잠금 대기 관계가 있습니다. | call-1 | +| 원천 관측 | 10:01 기록에도 같은 연결 번호의 대기 관계가 있습니다. | call-2 | +| 실행 기록 | 10:02 호출은 tool_timeout으로 실패해 결과를 확보하지 못했습니다. | call-3 | + +--- + +### 4. 원인 가설과 근거 + +가능성: 관측된 잠금 대기가 지연에 영향을 주었을 수 있습니다. [call-1, call-2] + +실제 지연과의 대응 자료가 없어 확정하지 않습니다. 조회 시간 초과는 이 가설을 강화하는 원천 근거가 아닙니다. [call-3] + +--- + +### 5. 조사 한계·조회 실패 + +마지막 시간 초과로 이후 대기의 존재·부재를 확인할 수 없습니다. [call-3] + +이를 DB 장애·과부하로 단정하지 않습니다. 앞선 성공 관측은 유지합니다. [call-1, call-2] + +지속 시간, 트랜잭션 동일성, 지연 영향과 전체 검사 범위는 확인되지 않았습니다. + +--- + +### 6. 후속 확인 사항 + +| 확인 항목 | 목적 | +|---|---| +| 지연 시각·요청-연결 대응과 당시 트랜잭션 | 성공한 관측과 증상의 관련성을 확인합니다. | +| 실패한 조회의 수집 경로와 후속 자료 확보 가능 여부 | 조회 공백의 이유와 이후 상태를 확인할 근거를 검토합니다. | + +확인 항목은 담당자 검토용이며 자동 재시도나 연결 종료 요청이 아닙니다. + +--- + +### 7. 호출별 상세 근거 + +| 호출 ID 약칭 | 도구 | 기록 시각 | 허용된 결과 또는 실패 | +|---|---|---|---| +| call-1 | mysql_get_lock_waits | 10:00:00 | 성공, 1행, 386→382 대기 관계, 잘림 false | +| call-2 | mysql_get_lock_waits | 10:01:00 | 성공, 1행, 386→382 대기 관계, 잘림 false | +| call-3 | mysql_get_lock_waits | 10:02:00 | tool_timeout. 결과 미확보이며 반환 0행이 아님 | + +--- + +### Discord 기대 출력 + +> **합성 예시 · 잠금 대기 조사 / 일부 조회 실패** +> +> **진단 ID:** diag-00000000-0000-4000-8000-00000000000b +> +> **조사 종료:** 판단 근거 부족 · 호출 3건, 성공 2건, 실패 1건 +> +> 두 조회에 386→382 대기 관계가 있습니다. [call-1, call-2] +> +> 마지막 조회는 시간 초과로 결과 미확보입니다. [call-3] 대기의 후속 상태·지연 원인·증상 해소는 미확인입니다. 전체 검사 범위도 확인되지 않았습니다. +> +> **후속 확인:** 지연과 연결의 대응, 트랜잭션 정보, 실패 조회의 수집 공백 +> +> **상세:** amdc-report.md · 개별 호출 상세 3건은 첨부 참조 + +--- + +### 현재 입력만 있을 때 + +> 두 조회는 각각 1행을 반환했고, 마지막은 tool_timeout으로 결과 미확보입니다. [call-1, call-2, call-3] +> +> 구체적인 관측 내용과 원인은 확인할 수 없습니다. 실패 이후 상태와 증상 해소 여부도 미확인입니다. + +성공 결과를 삭제하거나 시간 초과를 0행으로 쓰지 않습니다. + +--- + +## 사례 C: 관측 불일치와 근거 부족 + +합성 입력: `completion_reason=insufficient_evidence`. 동일한 기록 시각의 반환 내용이 다릅니다. 실제 측정 시점·필터가 같다는 자료는 없으므로 논리적 모순이나 상태 변화로 확정하지 않습니다. call-2의 진단 코멘트에는 “잠금 대기가 해소됐다”는 **미검증 해석**이 있다고 가정합니다. + +| 호출 | 기록 시각 | 실행 기록 | 조건부 정제 관측 | +|---|---|---|---| +| call-1 | 10:00:00 | success, 반환 1행, 잘림 false | 연결 386이 382의 잠금 해제를 기다리는 관계 | +| call-2 | 10:00:00 | success, 반환 0행, 잘림 false | 이번 조회의 반환 행 없음 | + +### 1. 진단 요약 + +한 조회에는 386→382의 대기 관계가 있고 다른 조회의 반환 행은 0건입니다. [call-1, call-2] + +기록 시각은 같습니다. [call-1, call-2] + +조회 조건과 측정 구간을 대조할 수 없어 결과 차이를 설명하지 못했습니다. 원인 가설과 정상·복구 판단을 보류합니다. + +--- + +### 2. 조사 대상·범위 + +사례 전제의 sample-db에 대한 두 기록을 비교했습니다. 두 기록의 시각 표기는 10:00 UTC입니다. [call-1, call-2] + +측정 구간·필터·실제 지연값이 미제공이어서 동일 조건의 반복 관측인지 확인할 수 없습니다. + +종료 이유는 판단 근거 부족입니다. + +--- + +### 3. 확인된 사실 + +| 종류 | 사실 | 호출 근거 | +|---|---|---| +| 원천 관측 | 10:00 기록에 연결 386→382의 대기 관계가 있습니다. | call-1 | +| 실행 기록 | 같은 기록 시각으로 표시된 다른 조회는 성공했고 반환 0행, 잘림 false입니다. | call-2 | + +--- + +### 4. 원인 가설과 근거 + +현재 근거로 원인 가설을 제시하지 않습니다. 서로 다른 반환 내용과 비교 조건 공백 때문에 어느 결과도 전체 상태를 대표한다고 판단할 수 없습니다. [call-1, call-2] + +기대하는 `suspected_cause`는 null입니다. call-2에 붙은 진단 해석은 해소를 입증하는 근거가 아닙니다. [call-2] + +--- + +### 5. 조사 한계·조회 실패 + +두 호출 모두 성공하고 잘림 표식은 false입니다. [call-1, call-2] + +조회 실패는 없지만 결과 불일치를 해석할 조건이 없습니다. 뒤 순번이나 코멘트만으로 앞선 관측을 무효화하지 않습니다. + +지연의 원인·현재 대기 상태·복구 여부는 미확인입니다. + +--- + +### 6. 후속 확인 사항 + +| 확인 항목 | 목적 | +|---|---| +| 두 호출의 검증된 대상·측정 구간·조회 조건 | 같은 조건에서 상충한 것인지 비교 불가능한 자료인지 구분합니다. | +| 지연 측정과 요청 대응 | 잠금 대기 관측과 사용자 증상을 연결할 자료를 확인합니다. | + +현재 자료를 유리한 결론으로 합치거나 자동으로 재조회하지 않습니다. + +--- + +### 7. 호출별 상세 근거 + +| 호출 ID 약칭 | 도구 | 기록 시각 | 허용된 결과와 해석 구분 | +|---|---|---|---| +| call-1 | mysql_get_lock_waits | 10:00:00 | 성공, 1행, 386→382 대기 관계, 잘림 false | +| call-2 | mysql_get_lock_waits | 10:00:00 | 성공, 0행, 잘림 false. 별도 진단 해석은 해소를 주장하나 검증되지 않음 | + +--- + +### Discord 기대 출력 + +> **합성 예시 · 잠금 대기 조사 / 판단 보류** +> +> **진단 ID:** diag-00000000-0000-4000-8000-00000000000c +> +> **조사 종료:** 판단 근거 부족 · 호출 2건, 성공 2건, 실패 0건 +> +> 한 조회에는 386→382 대기 관계가 있고 다른 조회는 반환 0행입니다. [call-1, call-2] +> +> 기록 시각은 같습니다. [call-1, call-2] 조회 조건·측정 구간이 없어 결과 차이를 설명하지 못했습니다. 원인·정상·복구 판단을 보류합니다. 해소됐다는 진단 해석도 미검증입니다. [call-2] +> +> **후속 확인:** 두 호출의 비교 조건과 지연 측정 자료 +> +> **상세:** amdc-report.md · 개별 호출 상세 2건은 첨부 참조 + +--- + +### 현재 입력만 있을 때 + +> 같은 기록 시각의 두 조회가 각각 1행과 0행을 반환했습니다. [call-1, call-2] +> +> 비교 조건·구체적 관측 내용이 없어 원인을 판단할 수 없습니다. 해소됐다는 진단 해석은 검증되지 않았습니다. [call-2] + +comment의 관찰·가설 문장을 사실로 복사하지 않고 원인 가설을 보류합니다. + +--- + +## 사례 D: 결과 잘림 + +합성 입력: `completion_reason=investigation_complete`. 1회 호출에서 반환 2행과 `truncated=true`가 기록됐습니다. 전체 행 수와 생략된 관계 수는 제공하지 않습니다. + +| 호출 | 기록 시각 | 실행 기록 | 조건부 정제 관측 | +|---|---|---|---| +| call-1 | 10:00:00 | success, 반환 2행, 잘림 true | 반환 부분에 386→382와 391→382의 잠금 대기 관계 | + +### 1. 진단 요약 + +반환된 부분에는 386→382와 391→382의 잠금 대기 관계가 있습니다. [call-1] + +결과가 잘려 전체 규모와 다른 대기 관계는 확인할 수 없습니다. [call-1] + +지연 원인과 증상 해소 여부는 미확정입니다. + +--- + +### 2. 조사 대상·범위 + +사례 전제의 sample-db에 대한 10:00 UTC 기록 한 건의 반환 부분만 검토했습니다. [call-1] + +조사 + +종료 이유는 진단 에이전트의 조사 종료이나, 결과 잘림 때문에 전체 데이터를 검토한 것은 아닙니다. [call-1] + +지연값·필터·측정 구간과 전체 검사 범위는 미제공입니다. + +--- + +### 3. 확인된 사실 + +| 종류 | 사실 | 호출 근거 | +|---|---|---| +| 원천 관측·실행 기록 | 성공한 조회의 반환 부분에 386→382와 391→382 관계가 있고 반환 2행, 잘림 true입니다. | call-1 | + +--- + +### 4. 원인 가설과 근거 + +가능성: 반환 부분의 잠금 대기가 지연과 관련됐을 수 있습니다. [call-1] + +요청-연결 대응과 전체 결과가 없어 연결 382를 유일한 원인이나 가장 큰 영향 지점으로 판단할 수 없습니다. + +--- + +### 5. 조사 한계·조회 실패 + +호출은 성공했으나 결과 잘림이 있습니다. [call-1] + +전체 대기 건수, 생략된 관계 수·종류·분포와 영향 순위는 알 수 없습니다. 반환 2행을 전체 2건으로 표시하지 않습니다. + +지연과의 인과관계·복구 여부, 전체 검사 충족도 미확인입니다. + +--- + +### 6. 후속 확인 사항 + +| 확인 항목 | 목적 | +|---|---| +| 허용된 수집 범위·잘림 조건과 추가 정제 자료 확보 가능 여부 | 생략된 범위와 전체 규모를 판단할 근거를 확인합니다. | +| 지연 요청과 반환된 연결 관계의 대응 | 관측된 대기가 실제 증상에 영향을 주었는지 검토합니다. | + +제한 해제·전체 원시 덤프·자동 추가 조회를 지시하지 않습니다. + +--- + +### 7. 호출별 상세 근거 + +| 호출 ID 약칭 | 도구 | 기록 시각 | 허용된 결과 요약 | +|---|---|---|---| +| call-1 | mysql_get_lock_waits | 10:00:00 | 성공, 반환 2행, 386→382·391→382, 잘림 true. 전체 건수 미확인 | + +--- + +### Discord 기대 출력 + +> **합성 예시 · 잠금 대기 조사 / 결과 잘림** +> +> **진단 ID:** diag-00000000-0000-4000-8000-00000000000d +> +> **조사 종료:** 진단 에이전트 조사 종료 · 호출 1건, 성공 1건, 실패 0건 +> +> 반환 부분에 386→382·391→382 대기 관계가 있습니다. [call-1] +> +> 결과가 잘려 전체 규모·다른 대기 관계·영향 순위는 미확인입니다. [call-1] 지연 원인·증상 해소와 전체 검사 충족도 확인되지 않았습니다. +> +> **후속 확인:** 잘림 범위와 추가 정제 자료 확보 가능 여부, 지연과의 대응 +> +> **상세:** amdc-report.md · 개별 호출 상세 1건은 첨부 참조 + +--- + +### 현재 입력만 있을 때 + +> 조회는 성공해 2행을 반환했고 결과 잘림이 있습니다. [call-1] +> +> 반환 내용과 전체 규모는 확인할 수 없어 원인과 증상 해소를 판단할 수 없습니다. + +연결 관계·전체 2건·상위 원인 순위를 만들지 않습니다. + +--- + +## 검증 기록 + +검토 대상은 이 파일의 고정 문구이며 현재 모델 출력의 성공률이 아니다. [템플릿 검증 구분](report-template-v0.1.md#검증과-인계)을 따른다. + +| 사례 | 반드시 보존할 차이 | 의미 검토에서 금지할 결론 | +|---|---|---| +| A | 앞선 성공, 마지막 0행, 증상 해소·전체 범위 미확인 | 전체 정상, 복구 완료, 연속 2분 대기 | +| B | 앞선 성공, call-3 시간 초과·결과 미확보, 이후 상태 미확인 | 0행으로 대체, 시간 초과를 DB 장애 원인으로 단정 | +| C | 서로 다른 반환 내용, 비교 조건 부재, 코멘트 미검증, 가설 보류 | 뒤 순번/코멘트가 정답, 정상/복구, 강제 가설 | +| D | 반환 부분과 잘림, 전체 규모·영향 순위 미확인 | 전체 2건, 382가 유일/최대 원인 | + +구조·배치는 사용자 합의가 완료됐다. 사례별 사람의 의미 검토·후속 계약 승인은 미실시이며, 제품 코드/모델·저장·전송·부하 테스트도 이 문서 작업에서는 실행하지 않는다. + +### 자동 구조 점검 재현 + +PowerShell 7에서 `docs/design`을 현재 경로로 두고 아래를 실행한다. 이는 문서 구조와 표식 검사다. `Length`는 현재 MVP 포매터와 같은 UTF-16 코드 단위로 세며 문구의 의미는 판정하지 않는다. + +```powershell +$ErrorActionPreference = 'Stop' +$text = Get-Content -LiteralPath './report-template-v0.1-examples.md' -Raw +$cases = [regex]::Matches($text, '(?ms)^## 사례 ([A-D]):.*?(?=^## 사례 |^## 검증 기록)') +if ($cases.Count -ne 4) { throw 'Expected four cases' } +$titles = @('진단 요약','조사 대상·범위','확인된 사실','원인 가설과 근거','조사 한계·조회 실패','후속 확인 사항','호출별 상세 근거') +$markers = @{ A=@('반환 0행','증상 해소','전체 검사'); B=@('시간 초과','결과 미확보','전체 검사'); C=@('조회 조건','측정 구간','판단을 보류','미검증'); D=@('잘려','전체 규모','영향 순위','전체 검사') } +$totalFacts = 0 +foreach ($case in $cases) { + $key = $case.Groups[1].Value + $body = $case.Value + for ($n=0; $n -lt 7; $n++) { + $heading = '### {0}. {1}' -f ($n+1),$titles[$n] + if ([regex]::Matches($body, '(?m)^'+[regex]::Escape($heading)+'\r?$').Count -ne 1) { throw "$key heading" } + } + $inputPart = ($body -split '(?m)^### 1\.')[0] + $ids = @([regex]::Matches($inputPart, '(?m)^\| (call-\d+) \|') | ForEach-Object { $_.Groups[1].Value }) + foreach ($ref in [regex]::Matches($body, 'call-\d+')) { + if ($ref.Value -notin $ids) { throw "$key unknown reference $($ref.Value)" } + } + $facts = [regex]::Match($body, '(?ms)^### 3\..*?(?=^### 4\.)').Value + $rows = @($facts -split '\r?\n' | Where-Object { $_ -match '^\| (원천 관측|실행 기록)' }) + if ($rows.Count -eq 0) { throw "$key missing facts" } + foreach ($row in $rows) { + if ($row -notmatch '\| call-\d+(, call-\d+)* \|$') { throw "$key uncited fact" } + } + $totalFacts += $rows.Count + $discord = [regex]::Match($body, '(?ms)^### Discord 기대 출력\r?\n(.*?)(?=^### 현재 입력만)').Groups[1].Value + $discord = (($discord -split '\r?\n' | Where-Object { $_ -match '^>( |$)' }) -replace '^> ?', '') -join "`n" + if ($discord.Length -eq 0 -or $discord.Length -gt 1900) { throw "$key Discord length" } + foreach ($marker in $markers[$key]) { + if (-not $discord.Contains($marker)) { throw "$key missing marker $marker" } + } + '{0}: facts={1}, calls={2}, Discord={3}' -f $key,$rows.Count,$ids.Count,$discord.Length +} +foreach ($file in @('report-template-v0.1.md','report-template-v0.1-examples.md','report-template-discussion-2026-09-22.md')) { + $summary = ((Get-Content -LiteralPath $file -Raw) -split '\r?\n\r?\n')[1] + if ($summary.Length -gt 200) { throw "$file summary exceeds 200" } + '{0}: summary={1}' -f $file,$summary.Length +} +'fact rows with references: {0}/{0}' -f $totalFacts +``` + +링크의 파일·절 존재 확인과 변경 범위의 `git diff --check`는 별도로 수행한다. 위 스크립트는 같은 ID가 내용상 올바른 근거인지, 자유형 문장이 과장됐는지 또는 실제 포매터가 이 출력과 일치하는지 검증하지 않는다. + +### 2026-10-02 문서 점검 결과 + +Windows / PowerShell 7에서 위 코드 블록을 실행했다. 별도 로컬 링크 점검은 세 문서의 상대 파일·절 링크 33개가 존재함을 확인했다. 과거 문서가 연결한 웹 페이지 전체를 재검토했다는 뜻은 아니다. + +| 항목 | 실제 결과 | +|---|---| +| 구획·호출 참조 | 4사례 × 7구획, 사례 밖/없는 호출 참조 0개 | +| 사실 표의 참조 | 9/9행에 해당 사례의 call ID 있음. 이 수치는 자동 구조 점검 결과 | +| Discord 예시 길이 | A 331, B 353, C 380, D 349 UTF-16 코드 단위. 빈 줄·강조 기호를 포함하며 모두 1,900 이하 | +| 요약 길이 | 템플릿 124자, 사례 120자, 기존 논의 113자. 모두 200 이하 | +| 중요한 한계 표식 | A 빈 결과·증상 해소 미확인, B 시간 초과·결과 미확보, C 비교 조건 공백·미검증 해석, D 잘림·전체 규모 미확인을 요약에 보존 | + +작성자 에이전트와 독립 검토 에이전트가 사례 입력표와 상세·요약·현재 입력 표현을 대조했다. C의 동일 시각 및 미검증 해석 문장에 호출 참조를 보완했다. 보완 후 고정 문구의 근거 없는 원인·정상·복구 단정은 A/B/C/D 각각 0건, 중요한 조회 실패·잘림·근거 부족 누락도 각각 0건이다. 표 밖에 반복한 관측 문장도 같은 사례의 근거에 연결했다. 이는 에이전트의 문구 검토 결과이며 자유형 의미의 자동 증명이나 사람의 최종 검토가 아니다. + +미검증: 사례별 사람의 의미 검토·후속 계약 승인, 정제 근거 생산자 구현, 현재 모델/포매터와의 실행 비교, 다수 한계·최대 크기 입력의 보존, 저장·실전송·동시성·메모리·복구 검증. 제품 통과율이나 프로젝트 완료로 보고하지 않는다. + +같은 날 가독성 편집에서 구획 구분선, 의미별 문단, Discord 문단 여백과 항목 강조를 반영했다. 위 길이는 편집 후 다시 측정한 값이다. 사례의 사실·가설·한계와 7구획 순서는 유지하며, 제품 포매터 구현은 변경하지 않는다. diff --git a/docs/design/report-template-v0.1.md b/docs/design/report-template-v0.1.md new file mode 100644 index 0000000..6ae388e --- /dev/null +++ b/docs/design/report-template-v0.1.md @@ -0,0 +1,266 @@ +# 보고서 템플릿 v0.1 + +사람이 읽는 7구획 보고서와 Discord 요약의 표현·근거·작성 책임을 정한다. 합성 사례의 기대 출력은 설계 기준이며, 현재 MVP의 입력 공백과 후속 계약 결정을 구분한다. 제품 스키마와 모델 권한은 변경하지 않는다. + +- **작성일:** 2026-10-02 · 상태: v0.1 구조 사용자 합의 완료, 제품 적용은 ready_for_design +- **관련 작업:** [이슈 #7](https://github.com/Aolda/amdc/issues/7), [PR #17](https://github.com/Aolda/amdc/pull/17) +- **코드 대조 기준:** `b65fa4820873e52a44e423cc362ad30e043d96e0` + +## v0.1 구조 합의와 개선 원칙 + +2026-10-02 사용자는 현재 구조를 기준으로 고정하고, 이후 테스트하면서 개선하기로 합의했다. 최초 문서 판본은 v0.1로 표기한다. + +- 상세 보고서의 7구획과 순서, 구획별 여백·구분선, 관측·가설·한계의 문단 분리, Discord 요약의 배치를 기준으로 삼는다. +- 이후 테스트에서는 이 기준과 사례별 기대 출력을 비교한다. 읽기 어려운 표현이나 사실·근거·한계 전달 문제가 확인되면 해당 사례와 기대 출력을 함께 보완하고 다시 검증한다. +- 이번 합의는 보고서의 구조·배치에 적용한다. 사례별 의미 검토, 정제된 입력 계약, 스키마·모델 권한 변경과 제품 구현 검증은 별도로 남는다. + +## 읽기 순서와 소유 범위 + +1. [기존 합의](report-template-discussion-2026-09-22.md#합의한-기본-방향) → 이 문서의 [설계 선택](#설계-선택) +2. [상세 보고서 템플릿](#상세-보고서-템플릿) → [Discord 요약](#discord-요약) +3. [구획별 입력과 작성 책임](#구획별-입력과-작성-책임) → [미결정 계약](#미결정-계약) +4. [대표 사례별 기대 출력](report-template-v0.1-examples.md) → [검증과 인계](#검증과-인계) + +이 문서는 읽기용 구성과 표현을 소유하고, 사례 문서는 합성 입력과 기대 문구를 소유한다. + +2026-09-22 논의는 당시 합의·제안 이력으로 보존한다. + +[설계 준비안](report-agent-preparation.md)은 생산자와 소비자의 차이 및 결정 순서, [V1 후단 설계](report-downstream-v1.md)는 기존 Backend 5xx의 7필드 후단을 소유한다. + +제품 계약은 [P0 진입점](../prd/current/README.md)의 번호 PRD에 있다. PRD 00은 범위, 01은 Run/SQLite, 02는 도구·시나리오 판정, 03은 증거·보고서·전달, 04는 실행 검증, 05는 실제 원천 매핑, 06은 인계·모델 권한을 소유한다. + +이 문서의 v0.1은 문서 판본이며 API/스키마 버전이 아니다. + +## 설계 선택 + +**Problem** + +독자가 조회 성공을 정상으로, 빈 결과를 복구로, 진단 코멘트를 원천 사실로 읽을 수 있다. 현재 MySQL 투영은 행 수·잘림만 남기므로 구체적 관측을 요구하는 템플릿을 프롬프트 변경만으로 채울 수 없다. + +**Analyze** + +현재 메타데이터만으로 모든 문구를 제한하면 즉시 재현하기 쉽지만 잠금 관계 같은 핵심 근거가 빠진다. 정제된 구조화 근거를 전제로 목표 출력을 설계하고 현재 가능한 표현을 병기하면 입력 공백이 드러나지만, 적용 전에 계약·검증 작업이 필요하다. 원시 결과 또는 자유형 코멘트를 사실로 복사하는 안은 근거 검증을 우회하므로 채택하지 않는다. + +**Action** + +두 번째 방식을 문서 설계로 선택한다. 사람용 7구획과 Discord 요약, 네 합성 사례, 입력·책임 표를 작성한다. 제품 코드·스키마·프롬프트·원천 호출은 범위 밖이다. 롤백은 이번 문서와 연결 문장만 되돌리는 것이다. + +**Result** + +고정 사례에서 근거 없는 원인·정상·복구 단정 0건, 중요한 실패·잘림 누락 0건, 사실 근거 참조 100%, Discord의 중요한 한계 보존을 확인한다. 구조 검증, 에이전트 의미 대조, 사람 검토와 제품 실행 검증을 별도로 기록한다. + +## 두 출력 경로와 해석 경계 + +| 구분 | 현재 소유 계약 | 이 템플릿과의 관계 | +|---|---|---| +| 기존 P0 V1 | PRD 03의 `monitoring-report` 1.1.0과 PRD 06의 `ReportAgentInputV1` | Backend 5xx 전용 7필드. 상태별 고정 문구와 `run_`/`tc_`/`ev_` 참조를 유지한다. MySQL 사례를 강제 변환하지 않는다. | +| 1차 MVP | PRD 03·06의 MVP 절, `diagnosis-report/1.0.0` | `diagnosis_id`, 호출 메타데이터, 해석, 한계 등을 파일에 저장한 뒤 재조회해 요약과 첨부를 만든다. P0 전체 완료가 아니다. | +| 사람용 템플릿 v0.1 | 이 설계 문서 | 7구획은 읽기 순서다. 7필드와 일대일 대응하지 않으며 새 저장 필드나 모델 출력 필드를 승인하지 않는다. | + +`success`는 호출 실행 성공이다. `investigation_complete`는 진단 에이전트의 조사 종료 이유다. 어느 값도 필수 검사 충족, 원인 확정, 전체 정상 또는 복구를 증명하지 않는다. + +`seq`는 접수 순서이며 연속 관측 시간이나 인과 순서가 아니다. 실패 호출의 `observed_at`을 성공한 원천 측정 시각으로 표시하지 않는다. + +## 상세 보고서 템플릿 + +보고서 머리에는 안전한 조사 이름, 같은 진단의 식별자, 보고서 생성 시각을 둔다. 생성 시각과 호출 기록 시각을 구분한다. + +대상·증상·환경을 입력에서 확인할 수 없으면 미제공으로 표시하며 원래 요청문이나 환경값을 다시 가져오지 않는다. + +**읽기용 배치** + +- 7개 구획은 같은 수준의 제목으로 표시하고, 구획 사이에는 빈 줄과 구분선을 둔다. +- 관측 내용, 가설, 판단 한계는 문단을 나눈다. 근거 ID는 해당 문장과 같은 문단에 둔다. +- 여러 호출을 대조하는 사실·상세 근거는 표로, 병렬적인 확인 항목은 목록이나 표로 표시한다. +- 제목·본문·표·목록 사이에 빈 줄을 둔다. 단순 줄바꿈을 여러 번 넣어 여백을 대신하지 않는다. +- Discord도 핵심 발견, 중요한 한계, 후속 확인, 상세 안내 사이에 빈 줄을 둔다. 여백과 강조 기호를 포함해 길이를 검증한다. + +### 1. 진단 요약 + +핵심 관측과 마지막 조회의 의미를 2~4문장으로 적는다. 가설 유무·원인 미확정 여부와 결론을 제한하는 실패·잘림을 함께 둔다. + +정상/복구 배지를 새로 만들지 않는다. + +문장 틀: “<허용된 관측>이 확인됐습니다. [call ID] <빈 결과·조회 실패·잘림> 때문에 <확인하지 못한 범위>가 남습니다. 원인은 <확정 근거가 없으면 미확정>입니다.” + +근거가 메타데이터뿐이면 “조회가 성공해 N행을 반환했다”까지만 쓴다. + +--- + +### 2. 조사 대상·범위 + +검증된 대상 별칭, 확인하려는 증상, 실제 호출·기록 시각, 관측 구간과 포함되지 않은 검사를 구분한다. + +미제공 항목은 생략해 조사 범위를 넓게 보이게 하지 않는다. 도구 이름만으로 실제 서버·필터·전체 범위를 추정하지 않는다. + +--- + +### 3. 확인된 사실 + +| 종류 | 사실 | 호출 근거 | +|---|---|---| +| 원천 관측 | 정제·타입·참조 검증을 통과한 값으로 조립한 문장 | 같은 진단의 call ID | +| 실행 기록 | 성공/빈 반환/시간 초과/잘림 등 실행기가 기록한 내용 | 같은 진단의 call ID | + +각 사실 행에는 근거를 둔다. 복수 호출을 묶으면 그 호출을 모두 적는다. 숫자·단위·시각·범위는 입력과 일치해야 한다. + +`diagnostic_comment.observation`은 이 표에 복사하지 않는다. 원천 관측이 없으면 실행 기록만 표시하고 그 한계를 적는다. + +--- + +### 4. 원인 가설과 근거 + +가설마다 “가능성” 표시, 뒷받침하는 성공 관측, 반대되거나 설명하지 못한 관측, 확인에 필요한 정보를 연결한다. 실패 호출은 수집 공백의 근거이며 그 자체로 장애 원인의 근거가 아니다. + +설명력이 부족하거나 관측이 상충하면 “현재 근거로 원인 가설을 제시하지 않습니다”를 허용한다. 모델의 `null`을 실패나 억지 가설로 대체하지 않는다. + +이 절 전체를 모델에 작성시키지 않는다. 모델이 쓸 수 있는 값은 현재와 같이 `suspected_cause` 하나다. + +근거 연결·반대 관측의 구조화 및 고정 한계 표시 방식은 후속 계약 대상이다. 가설 안에 ID가 있다는 사실만으로 내용의 타당성이 검증되지는 않는다. + +--- + +### 5. 조사 한계·조회 실패 + +| 한계/실패 | 근거 | 판단에 미치는 영향 | +|---|---|---| +| 시간 초과 또는 권한 거부 | 해당 call ID와 안전한 코드/고정 설명 | 그 호출의 원천 상태를 확인할 수 없음 | +| 결과 잘림 | 해당 call ID | 반환 부분 밖의 존재·규모·분포를 알 수 없음 | +| 증상 연결·측정 구간 등 미제공 | 제공 자료의 범위 또는 해당 call ID | 원인·지속 시간·영향·복구 판단 불가 | + +빈 결과는 실패로 바꾸지 않고, 실패는 0행으로 표시하지 않는다. `truncated=false`는 반환 잘림 표식이 없다는 뜻이며 완전 조사 증거가 아니다. + +앞선 성공 관측은 뒤의 실패 때문에 제거하지 않는다. + +--- + +### 6. 후속 확인 사항 + +확인 항목, 미확인 정보와의 연결, 확인 목적을 표로 적는다. 담당자의 검토 항목이며 자동 추가 호출·재시도·운영 조치가 아니다. 조사 권한이나 도구가 있다고 가정하지 않으며 실행 명령·SQL·URL·연결 종료를 제안하지 않는다. + +사례별 구체적 문구는 설계 목표이고 현재 고정 `recommended_next_action`의 변경은 PRD 03에서 결정한다. + +--- + +### 7. 호출별 상세 근거 + +접수 순서대로 call ID, 도구, 기록 시각, 성공/실패, 안전한 결과 요약, 잘림과 오류를 표시한다. 사실과 별도 표시한 진단 해석은 같은 호출에 연결한다. + +원시 행·HTTP 본문·셸 출력·자유형 오류·요청/인수 원문은 포함하지 않는다. 사람이 읽는 상세 근거도 허용된 정제 근거의 표시이며 원시 덤프가 아니다. + +## Discord 요약 + +저장 후 재조회한 동일 보고서에서 코드가 결정적으로 만든다. 새 모델 호출이나 새 결론은 없다. + +MVP는 `diagnosis_id`와 `amdc-report.md`를 사용하고, 기존 V1의 Run 조회 안내와 혼합하지 않는다. 실제 MVP에 없는 REST 조회 URL을 만들지 않는다. + +표시 순서 제안: + +1. 조사 이름, 진단 ID, 조사 종료 설명과 호출 성공/실패 수 +2. 핵심 사실과 해당 호출 ID +3. 원인 가설 또는 판단 보류, 중요한 실패·잘림·상충·근거 부족과 판단 영향 +4. 후속 확인의 목적, 상세 첨부 안내, 생략한 호출 상세 개수 + +PRD 03의 1,900자 한도를 유지한다. 길이가 부족하면 반복 설명과 개별 호출 상세, 가설 부연부터 항목 단위로 생략한다. 중요한 한계는 고정된 짧은 문장과 영향을 받은 ID/개수로 남긴다. 여러 실패는 유형별로 묶되 실패 유형이나 결과 공백을 없애지 않는다. 사실이 줄어도 한계와 진단 식별자는 남아야 한다. 한계를 포함한 필수 요약도 한도에 맞출 수 없으면 조용히 자르지 않는 실패 정책을 PRD 03에서 확정한다. + +현재 `mvp-discord-formatter.ts`는 한계 목록을 360자로 미리보기하고 호출 두 건만 표시한다. 따라서 모든 입력에서 위 보존 기준을 충족한다고 주장할 수 없다. + +네 문서 예시의 길이 통과는 현재 포매터나 최악 크기 입력의 검증 결과가 아니다. + +## 구획별 입력과 작성 책임 + +현재 제공 여부는 `src/report-agent/mvp-report.ts`의 `execution`, `parseHandoff`, `createMvpReport`와 `src/reports/mvp-discord-formatter.ts`를 기준으로 한다. 아래 “필요 입력”은 의미 요구사항이며 확정 DTO 필드명이 아니다. + +### 입력·책임: 진단 요약 + +- **필요한 입력:** 검증된 핵심 사실, 조사 종료 설명, 중요한 한계 +- **현재 제공 정보와 공백:** 호출 수·성공/실패·종료 이유·일반 한계는 있음. 도메인별 사실과 증상 연결은 없음 +- **작성 책임:** 코드는 사실·한계 요약, 모델은 가설 한 필드만 +- **후속 소유 계약:** PRD 03·06 + +### 입력·책임: 조사 대상·범위 + +- **필요한 입력:** 안전한 대상/증상, 검사 목적·조건, 측정 구간·누락 검사 +- **현재 제공 정보와 공백:** tool/plugin/기록 시각은 있음. request/input은 투영 제외. 대상·필터·측정 구간·필수 검사 충족은 모름 +- **작성 책임:** 코드가 검증된 메타데이터만 표시. 모델 추정 금지 +- **후속 소유 계약:** PRD 00·02·05·06 + +### 입력·책임: 확인된 사실 + +- **필요한 입력:** 도구별 정제 값·단위·출처·같은 진단의 call ID +- **현재 제공 정보와 공백:** MySQL은 반환 행 수·잘림만 있음. HTTP는 상태 코드, shell은 종료 코드만 있음. MySQL 잠금 관계·내용은 없음 +- **작성 책임:** 정규화/검증 뒤 코드 조립. comment는 해석으로 분리 +- **후속 소유 계약:** PRD 03·05·06 + +### 입력·책임: 원인 가설과 근거 + +- **필요한 입력:** 허용 관측, 찬성·반대 근거, 미확인 정보 +- **현재 제공 정보와 공백:** `diagnostic_comment`, 관련 ID는 있음. 사실성/인과관계 검증은 아님. 모델은 `suspected_cause` 또는 null 반환 +- **작성 책임:** 모델 권한 유지. 코드가 참조/표시·한계 보존, 의미는 별도 검토 +- **후속 소유 계약:** PRD 03·06 + +### 입력·책임: 조사 한계·조회 실패 + +- **필요한 입력:** 호출별 오류, 잘림, 수집 공백과 결론 영향 +- **현재 제공 정보와 공백:** 오류 코드·잘림 요약·일반 limitations 있음. 완전성/상충/영향의 typed 계약은 없음 +- **작성 책임:** 코드가 결정적으로 표시. 모델의 한계 누락으로 삭제되지 않음 +- **후속 소유 계약:** PRD 03·06 + +### 입력·책임: 후속 확인 사항 + +- **필요한 입력:** 미확인 항목과 확인 목적의 검증된 대응 +- **현재 제공 정보와 공백:** 상태별 코드 문구 있음. 연결/트랜잭션별 구체 문구는 없음 +- **작성 책임:** 코드 정책. 모델이 조치·도구 호출을 생성하지 않음 +- **후속 소유 계약:** PRD 02·03 + +### 입력·책임: 호출별 상세 근거 + +- **필요한 입력:** 순서·ID·도구·기록 시각·정제 결과·실패·해석 구분 +- **현재 제공 정보와 공백:** 메타데이터와 해석은 있음. 원천 세부 사실·원천 계약 버전은 없음 +- **작성 책임:** 코드가 검증·조립하고 저장된 객체에서 표시 +- **후속 소유 계약:** PRD 03·05·06 + +### 입력·책임: Discord + +- **필요한 입력:** 저장된 핵심 사실·중요 한계·안전한 생략 정보 +- **현재 제공 정보와 공백:** 저장/재조회·첨부 있음. 360자 한계 미리보기의 중요도 보존은 미보장 +- **작성 책임:** 코드 전용 투영 +- **후속 소유 계약:** PRD 03·04 + +현재 입력만으로 쓸 수 있는 문장: “call-1은 조회에 성공해 1행을 반환했습니다.” 쓸 수 없는 문장: “연결 386이 382를 기다렸습니다.” + +후자는 전용 정규화기가 검증한 잠금 관계가 있어야 한다. 코멘트에 번호가 적혀 있어도 차이를 메우지 못한다. + +## 미결정 계약 + +| 결정 | 다음 검토에서 구체화할 내용 | 결정 위치·검토 역할 | +|---|---|---| +| 정제된 MySQL 근거 | 허용 사실 종류·타입·값/관계 검증, 안전한 식별자 치환과 동일성 범위, 원천 계약 버전, 항목·전체 크기 상한 | PRD 03·05·06, 생산자/Tool Core와 Report 담당 | +| 조사 범위·시간 | 대상 별칭·증상 요약의 허용 여부, 필터/관측 구간의 안전한 표현, 기록 시각 의미, 필수 검사·완전성·상충 판정 | PRD 00·02·05·06, 시나리오/생산자 담당 | +| 저장·표시 연결 | 현재 MVP의 확장 여부와 정확한 버전, 승인된 사실/한계/가설 근거의 영속 표현, 구버전 거부·호환 정책 | PRD 03·06. P0 Run/SQLite 변경이 필요하면 PRD 01도 별도 검토 | +| 요약·후속 확인 | 사실 기반 요약과 한계별 확인 항목, Discord 필수 정보·생략 순서·초과 시 동작 | PRD 03·04, Report 담당과 Discord 통합 검토자 | + +권고는 정제된 근거 계약을 먼저 닫고 코드 조립을 확장하는 것이다. 모델 권한 확대와 원시 결과 재유입은 이 권고에 포함되지 않는다. + +숫자 상한·새 스키마 버전·필드명·신규 MySQL 판정은 이 문서에서 확정하지 않는다. 필요한 사용자/계약 담당자 결정이 남으면 해당 구현 게이트를 열지 않는다. + +## 검증과 인계 + +검증 단위는 사례 A~D의 입력표, 상세 보고서, Discord 요약과 현재 입력 표현이다. 문서 예시는 제품이 실제 생성한 출력이나 실행 가능한 `DiagnosisHandoff` fixture가 아니다. + +| 검증 종류 | 점검할 것 | 판정 범위 | +|---|---|---| +| 자동 구조 점검 | 4사례 × 7구획, 사실 행·호출 참조의 존재/사례 내 일치, Discord 1,900자, 필수 실패·잘림 표식, 링크, 요약 200자 | 문서 구조·표식만. 자유형 문장의 인과 타당성은 증명하지 않음 | +| 에이전트 의미 대조 | 모든 관측의 값·시각·범위와 근거 비교, 빈 결과/실패 구별, 상충 보류, 가설/미확인 구별, 한계 누락 | 고정 문구를 읽어 대조한 결과. 사람 승인이나 모델 품질 평가가 아님 | +| 사람의 의미 검토 | 정제 근거 가정과 표현의 이해 가능성, 후속 계약 수용 여부 | 구조·배치는 사용자 합의 완료. 사례별 의미 검토와 후속 계약 승인은 남음 | +| 제품 검증 | 정규화·모델·저장·포매터의 실제 산출물과 fixture 비교 | 이번 작업에서 실행하지 않음. 후속 구현의 PRD 04 대상 | + +이번 문서 검증 결과와 재현 방법은 [사례 문서의 검증 기록](report-template-v0.1-examples.md#검증-기록)에 둔다. 제품 테스트·성능·실 원천/LiteLLM/Discord 검증으로 확대 해석하지 않는다. + +다음 채팅 하나의 산출물은 **정제된 근거 입력 계약 설계**다. 위 미결정 표를 소유 PRD에 연결해 허용 필드·신뢰 경계·정규화·크기·버전·실패·호환 정책과 네 사례의 생산자→소비자 대응을 검토 가능한 계약안으로 만든다. + +먼저 설계를 닫고 구현 필요 범위를 정한다. 이번 템플릿만으로 제품 코드를 시작하지 않는다. + +다음 작업의 성공 기준: 네 사례의 사실·실패·잘림·상충을 손실 없이 표현할 수 있고, 원시 결과/미검증 코멘트의 사실 승격 경로가 없으며, 누락·다른 진단 ID·잘못된 타입·상한 초과를 거부하는 검증 계획과 계약 담당 결정이 명시돼야 한다. + +미승인 계약은 미결정으로 남긴다. [이슈 #7](https://github.com/Aolda/amdc/issues/7)과 [PR #17](https://github.com/Aolda/amdc/pull/17)을 연결하되 이 문서 완료를 이슈 종료·PR 병합·P0 완료로 표시하지 않는다. From 8440c2f2a042754aec9da2ab0f0966c1775fb14c Mon Sep 17 00:00:00 2001 From: DongHun Date: Sat, 3 Oct 2026 00:42:38 +0900 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20=EA=B8=B0=EB=8C=80=20=EB=B3=B4?= =?UTF-8?q?=EA=B3=A0=EC=84=9C=EC=9D=98=20=EB=A8=B8=EB=A6=AC=EB=A7=90?= =?UTF-8?q?=EA=B3=BC=20=EC=9A=94=EC=95=BD=20=EA=B7=BC=EA=B1=B0=EB=A5=BC=20?= =?UTF-8?q?=EA=B2=80=EC=A6=9D=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/design/report-template-v0.1-examples.md | 67 ++++++++++++++++++-- docs/design/report-template-v0.1.md | 2 +- 2 files changed, 61 insertions(+), 8 deletions(-) diff --git a/docs/design/report-template-v0.1-examples.md b/docs/design/report-template-v0.1-examples.md index 520be29..d8d65b2 100644 --- a/docs/design/report-template-v0.1-examples.md +++ b/docs/design/report-template-v0.1-examples.md @@ -30,7 +30,7 @@ - C 진단 ID: `diag-00000000-0000-4000-8000-00000000000c` - D 진단 ID: `diag-00000000-0000-4000-8000-00000000000d` -공통 사례 전제: 합성 대상 별칭은 `sample-db`, 도구는 `mysql_get_lock_waits`, 검토 목적은 요청된 지연과 잠금 대기의 관련성 확인이다. 대상 별칭·검토 목적도 현재 Report 투영에는 없다. 시간은 모두 2026-09-18 UTC의 호출 기록 시각이며 측정 구간·연속 관측을 뜻하지 않는다. +공통 사례 전제: 합성 대상 별칭은 `sample-db`, 도구는 `mysql_get_lock_waits`, 검토 목적은 요청된 지연과 잠금 대기의 관련성 확인이다. 대상 별칭·검토 목적도 현재 Report 투영에는 없다. 입력표의 시간은 모두 2026-09-18 UTC의 호출 기록 시각이며 측정 구간·연속 관측을 뜻하지 않는다. 상세 보고서의 생성 시각은 별도의 합성 값인 2026-09-18T10:03:00.000Z로 둔다. 실제 요청 지연, 요청-연결 대응, 필터·전체 검사 범위, 트랜잭션 동일성·상태는 제공하지 않는다. 아래 “미제공” 판단은 이 사례 전제에 근거한다. @@ -46,13 +46,21 @@ | call-2 | 10:01:00 | success, 반환 1행, 잘림 false | 연결 386이 382의 잠금 해제를 기다리는 관계 | | call-3 | 10:02:00 | success, 반환 0행, 잘림 false | 이번 조회의 반환 행 없음 | +**상세 보고서** + +**조사 이름:** 잠금 대기 조사 (합성 사례 A) + +**진단 식별자:** diag-00000000-0000-4000-8000-00000000000a + +**보고서 생성 시각:** 2026-09-18T10:03:00.000Z + ### 1. 진단 요약 앞선 두 조회에 연결 386이 382의 잠금 해제를 기다리는 관계가 기록됐습니다. [call-1, call-2] 마지막 조회의 반환 행은 0건입니다. [call-3] -잠금 대기가 지연에 영향을 주었을 가능성은 있으나 원인은 미확정이며, 빈 결과만으로 증상 해소를 확인할 수 없습니다. +잠금 대기가 지연에 영향을 주었을 가능성은 있으나 원인은 미확정이며, 빈 결과만으로 증상 해소를 확인할 수 없습니다. [call-1, call-2, call-3] --- @@ -152,13 +160,21 @@ | call-2 | 10:01:00 | success, 반환 1행, 잘림 false | 연결 386이 382의 잠금 해제를 기다리는 관계 | | call-3 | 10:02:00 | error, tool_timeout, 결과 미확보 | 없음. 0행으로 대체하지 않음 | +**상세 보고서** + +**조사 이름:** 잠금 대기 조사 (합성 사례 B) + +**진단 식별자:** diag-00000000-0000-4000-8000-00000000000b + +**보고서 생성 시각:** 2026-09-18T10:03:00.000Z + ### 1. 진단 요약 성공한 두 조회에 연결 386→382의 잠금 대기가 기록됐습니다. [call-1, call-2] 마지막 조회는 시간 초과로 결과를 얻지 못했습니다. [call-3] -지연 원인은 미확정이며 대기의 후속 상태와 증상 해소 여부도 알 수 없습니다. +지연 원인은 미확정이며 대기의 후속 상태와 증상 해소 여부도 알 수 없습니다. [call-1, call-2, call-3] --- @@ -260,13 +276,21 @@ | call-1 | 10:00:00 | success, 반환 1행, 잘림 false | 연결 386이 382의 잠금 해제를 기다리는 관계 | | call-2 | 10:00:00 | success, 반환 0행, 잘림 false | 이번 조회의 반환 행 없음 | +**상세 보고서** + +**조사 이름:** 잠금 대기 조사 (합성 사례 C) + +**진단 식별자:** diag-00000000-0000-4000-8000-00000000000c + +**보고서 생성 시각:** 2026-09-18T10:03:00.000Z + ### 1. 진단 요약 한 조회에는 386→382의 대기 관계가 있고 다른 조회의 반환 행은 0건입니다. [call-1, call-2] 기록 시각은 같습니다. [call-1, call-2] -조회 조건과 측정 구간을 대조할 수 없어 결과 차이를 설명하지 못했습니다. 원인 가설과 정상·복구 판단을 보류합니다. +조회 조건과 측정 구간을 대조할 수 없어 결과 차이를 설명하지 못했습니다. 원인 가설과 정상·복구 판단을 보류합니다. [call-1, call-2] --- @@ -363,13 +387,21 @@ comment의 관찰·가설 문장을 사실로 복사하지 않고 원인 가설 |---|---|---|---| | call-1 | 10:00:00 | success, 반환 2행, 잘림 true | 반환 부분에 386→382와 391→382의 잠금 대기 관계 | +**상세 보고서** + +**조사 이름:** 잠금 대기 조사 (합성 사례 D) + +**진단 식별자:** diag-00000000-0000-4000-8000-00000000000d + +**보고서 생성 시각:** 2026-09-18T10:03:00.000Z + ### 1. 진단 요약 반환된 부분에는 386→382와 391→382의 잠금 대기 관계가 있습니다. [call-1] 결과가 잘려 전체 규모와 다른 대기 관계는 확인할 수 없습니다. [call-1] -지연 원인과 증상 해소 여부는 미확정입니다. +지연 원인과 증상 해소 여부는 미확정입니다. [call-1] --- @@ -377,8 +409,6 @@ comment의 관찰·가설 문장을 사실로 복사하지 않고 원인 가설 사례 전제의 sample-db에 대한 10:00 UTC 기록 한 건의 반환 부분만 검토했습니다. [call-1] -조사 - 종료 이유는 진단 에이전트의 조사 종료이나, 결과 잘림 때문에 전체 데이터를 검토한 것은 아닙니다. [call-1] 지연값·필터·측정 구간과 전체 검사 범위는 미제공입니다. @@ -483,6 +513,7 @@ if ($cases.Count -ne 4) { throw 'Expected four cases' } $titles = @('진단 요약','조사 대상·범위','확인된 사실','원인 가설과 근거','조사 한계·조회 실패','후속 확인 사항','호출별 상세 근거') $markers = @{ A=@('반환 0행','증상 해소','전체 검사'); B=@('시간 초과','결과 미확보','전체 검사'); C=@('조회 조건','측정 구간','판단을 보류','미검증'); D=@('잘려','전체 규모','영향 순위','전체 검사') } $totalFacts = 0 +$totalSummaryParagraphs = 0 foreach ($case in $cases) { $key = $case.Groups[1].Value $body = $case.Value @@ -491,6 +522,19 @@ foreach ($case in $cases) { if ([regex]::Matches($body, '(?m)^'+[regex]::Escape($heading)+'\r?$').Count -ne 1) { throw "$key heading" } } $inputPart = ($body -split '(?m)^### 1\.')[0] + $header = [regex]::Match($inputPart, '(?ms)^\*\*상세 보고서\*\*\r?\n(.*)$').Groups[1].Value + $expectedId = 'diag-00000000-0000-4000-8000-00000000000' + $key.ToLowerInvariant() + $expectedMetadata = @(('**조사 이름:** 잠금 대기 조사 (합성 사례 ' + $key + ')'), ('**진단 식별자:** ' + $expectedId), '**보고서 생성 시각:** 2026-09-18T10:03:00.000Z') + foreach ($line in $expectedMetadata) { + if ([regex]::Matches($header, '(?m)^' + [regex]::Escape($line) + '\r?$').Count -ne 1) { throw "$key missing or mismatched report metadata" } + } + $summary = [regex]::Match($body, '(?ms)^### 1\. 진단 요약\r?\n(.*?)(?=^### 2\.)').Groups[1].Value + $paragraphs = @($summary -split '\r?\n\s*\r?\n' | ForEach-Object { $_.Trim() } | Where-Object { $_ -and $_ -ne '---' }) + if ($paragraphs.Count -ne 3) { throw "$key expected three summary paragraphs" } + foreach ($paragraph in $paragraphs) { + if ($paragraph -notmatch '\[call-\d+(, call-\d+)*\]$') { throw "$key uncited summary paragraph" } + } + $totalSummaryParagraphs += $paragraphs.Count $ids = @([regex]::Matches($inputPart, '(?m)^\| (call-\d+) \|') | ForEach-Object { $_.Groups[1].Value }) foreach ($ref in [regex]::Matches($body, 'call-\d+')) { if ($ref.Value -notin $ids) { throw "$key unknown reference $($ref.Value)" } @@ -516,6 +560,7 @@ foreach ($file in @('report-template-v0.1.md','report-template-v0.1-examples.md' '{0}: summary={1}' -f $file,$summary.Length } 'fact rows with references: {0}/{0}' -f $totalFacts +'summary paragraphs with references: {0}/{0}' -f $totalSummaryParagraphs ``` 링크의 파일·절 존재 확인과 변경 범위의 `git diff --check`는 별도로 수행한다. 위 스크립트는 같은 ID가 내용상 올바른 근거인지, 자유형 문장이 과장됐는지 또는 실제 포매터가 이 출력과 일치하는지 검증하지 않는다. @@ -537,3 +582,11 @@ Windows / PowerShell 7에서 위 코드 블록을 실행했다. 별도 로컬 미검증: 사례별 사람의 의미 검토·후속 계약 승인, 정제 근거 생산자 구현, 현재 모델/포매터와의 실행 비교, 다수 한계·최대 크기 입력의 보존, 저장·실전송·동시성·메모리·복구 검증. 제품 통과율이나 프로젝트 완료로 보고하지 않는다. 같은 날 가독성 편집에서 구획 구분선, 의미별 문단, Discord 문단 여백과 항목 강조를 반영했다. 위 길이는 편집 후 다시 측정한 값이다. 사례의 사실·가설·한계와 7구획 순서는 유지하며, 제품 포매터 구현은 변경하지 않는다. + +### 2026-10-03 PR 검토 후 보완 + +네 상세 기대 출력에 조사 이름·같은 진단 ID·합성 보고서 생성 시각을 추가했다. 생성 시각은 호출 기록 시각과 구분한다. 각 사례의 요약 결론에도 호출 참조를 붙이고, D의 대상·범위에 남은 문장 조각을 제거했다. + +Windows / PowerShell 7에서 확장한 구조 점검이 통과했다. 4개 머리말의 세 항목과 진단 ID 일치, 요약 12/12문단의 참조, 기존 4×7구획·사실 9/9행·Discord 길이·요약 길이를 확인했다. 참조의 내용상 타당성은 별도 문구 검토로 대조했다. + +임시 사본에서 조사 이름·진단 ID·생성 시각을 각각 삭제하거나 다른 사례의 진단 ID로 바꾸거나 요약의 마지막 참조·문단 하나를 삭제한 여섯 변형은 모두 점검에서 거부됐다. 원본은 복원 후 재검증했다. 이는 문서의 회귀 점검이며 제품 실행이나 사례별 사람의 최종 의미 검토를 대신하지 않는다. diff --git a/docs/design/report-template-v0.1.md b/docs/design/report-template-v0.1.md index 6ae388e..ee641cd 100644 --- a/docs/design/report-template-v0.1.md +++ b/docs/design/report-template-v0.1.md @@ -250,7 +250,7 @@ PRD 03의 1,900자 한도를 유지한다. 길이가 부족하면 반복 설명 | 검증 종류 | 점검할 것 | 판정 범위 | |---|---|---| -| 자동 구조 점검 | 4사례 × 7구획, 사실 행·호출 참조의 존재/사례 내 일치, Discord 1,900자, 필수 실패·잘림 표식, 링크, 요약 200자 | 문서 구조·표식만. 자유형 문장의 인과 타당성은 증명하지 않음 | +| 자동 구조 점검 | 4사례 × 7구획, 보고서 머리말의 조사 이름·진단 ID·생성 시각, 사실 행·요약 문단의 호출 참조와 사례 내 일치, Discord 1,900자, 필수 실패·잘림 표식, 링크, 요약 200자 | 문서 구조·표식만. 자유형 문장의 인과 타당성은 증명하지 않음 | | 에이전트 의미 대조 | 모든 관측의 값·시각·범위와 근거 비교, 빈 결과/실패 구별, 상충 보류, 가설/미확인 구별, 한계 누락 | 고정 문구를 읽어 대조한 결과. 사람 승인이나 모델 품질 평가가 아님 | | 사람의 의미 검토 | 정제 근거 가정과 표현의 이해 가능성, 후속 계약 수용 여부 | 구조·배치는 사용자 합의 완료. 사례별 의미 검토와 후속 계약 승인은 남음 | | 제품 검증 | 정규화·모델·저장·포매터의 실제 산출물과 fixture 비교 | 이번 작업에서 실행하지 않음. 후속 구현의 PRD 04 대상 |