From a223d42f9aae5f59e22fa75fb865a883fec41fee Mon Sep 17 00:00:00 2001 From: kyeongmin Date: Wed, 1 Apr 2026 17:07:52 +0900 Subject: [PATCH] Strengthen step issue files with KPI-based evaluation rules --- issues/README.md | 28 ++++------ issues/Step-1-Input-Review.md | 63 ++++++++++++++++++----- issues/Step-2-Interpretation.md | 63 ++++++++++++++++++----- issues/Step-3-Content-Structuring.md | 62 +++++++++++++++++----- issues/Step-4-Execution-Planning.md | 56 ++++++++++++++++---- issues/Step-5-Execution.md | 49 ++++++++++++++---- issues/Step-6-Validation-and-Recording.md | 50 +++++++++++++++--- 7 files changed, 282 insertions(+), 89 deletions(-) diff --git a/issues/README.md b/issues/README.md index aae5962..47605a8 100644 --- a/issues/README.md +++ b/issues/README.md @@ -1,22 +1,14 @@ # Step Issue Usage -이 폴더의 문서들은 코드에 넣기 위한 문서가 아니라, Gitea `이슈` 탭에 그대로 붙여 넣기 위한 step별 이슈 본문 초안이다. +이 폴더의 문서들은 Gitea `이슈` 탭에 그대로 붙여 넣기 위한 step별 이슈 본문 초안이다. -## 생성 순서 -1. Step 1 이슈 생성 -2. Step 2 이슈 생성 -3. Step 3 이슈 생성 -4. Step 4 이슈 생성 -5. Step 5 이슈 생성 -6. Step 6 이슈 생성 +## 사용 방식 +1. Step별 새 이슈를 만든다. +2. 해당 step 문서 내용을 붙여 넣는다. +3. 실제 실행 결과는 이슈 코멘트로 남긴다. -## 각 이슈에 반드시 들어갈 항목 -- 목적 -- 입력 -- 실행 방법 -- 성공 기준 -- 실패 기준 -- 실패 분류 -- 실제 결과 -- 판정 -- 다음 단계 전달물 +## 공통 원칙 +- 모든 step 이슈는 KPI 기반 성공/실패 기준을 가진다. +- `pass / revise / fail` 판정 규칙을 포함한다. +- 실패 분류와 수정 액션 가이드를 포함한다. +- 실제 결과와 판정은 코멘트로 누적한다. diff --git a/issues/Step-1-Input-Review.md b/issues/Step-1-Input-Review.md index b811189..8365e4e 100644 --- a/issues/Step-1-Input-Review.md +++ b/issues/Step-1-Input-Review.md @@ -2,7 +2,7 @@ Step 1 / 입력 확인 ## 목적 -현재 입력 문서를 읽고 작업 목적, 범위, 제약을 명확히 한다. +입력 문서를 실행 가능한 단위로 식별하고, 작업 목적과 범위와 제약을 확정한다. ## 입력 - 입력 폴더: @@ -12,31 +12,65 @@ Step 1 / 입력 확인 ## 실행 방법 1. 입력 문서를 읽는다. -2. 요청 목적을 정리한다. -3. 작업 범위를 정리한다. -4. 주요 제약을 정리한다. -5. 확인이 필요한 항목을 남긴다. +2. 아래 `필수 산출 항목` 6개를 작성한다. +3. 각 항목의 충족 여부를 체크한다. +4. `판정 규칙`에 따라 pass / revise / fail을 결정한다. +5. 실패 시 `수정 액션`을 기록한다. + +## 필수 산출 항목 +- A1. 입력 파일 경로 1개 +- A2. 문서 제목 1개 +- A3. 작업 목적 1문장 +- A4. 작업 범위 1~3개 항목 +- A5. 주요 제약 3개 이상 +- A6. 확인 필요 사항 0개 이상 ## 성공 기준 -- 입력 파일이 명확히 식별된다. -- 요청 목적이 정리된다. -- 작업 범위가 정리된다. -- 주요 제약이 기록된다. +- A1~A6 전부 작성됨 +- 작업 목적은 1문장으로 끝남 +- 작업 범위는 1~3개 항목으로 제한됨 +- 주요 제약은 최소 3개 기록됨 +- 산출물이 지정 경로에 저장됨 ## 실패 기준 -- 입력 파일이 불명확하다. -- 목적이 모호하다. -- 제약이 누락되었다. +- 입력 파일 경로 미기록 +- 문서 제목 미기록 +- 작업 목적 미기록 또는 2문장 이상으로 장황함 +- 작업 범위 0개 또는 4개 이상 +- 주요 제약 2개 이하 +- 산출물 파일 미생성 + +## KPI / 판정 규칙 +- 충족률 = 충족 항목 수 / 6 +- `pass`: 충족률 100% and 치명 항목(A1, A2, A3) 모두 충족 +- `revise`: 충족률 83% 이상 100% 미만 and 치명 항목 모두 충족 +- `fail`: 충족률 83% 미만 or 치명 항목 1개 이상 누락 ## 실패 분류 -- Input +- `Input-Path`: 입력 파일 식별 실패 +- `Input-Purpose`: 작업 목적 정리 실패 +- `Input-Scope`: 범위 정의 실패 +- `Input-Constraint`: 제약 추출 부족 +- `Input-Artifact`: 산출물 저장 실패 + +## 수정 액션 가이드 +- `Input-Path`: 입력 파일 경로를 1개로 특정하고 링크/경로를 다시 기록 +- `Input-Purpose`: 목적을 1문장으로 다시 축약 +- `Input-Scope`: 범위를 1~3개로 다시 제한 +- `Input-Constraint`: 제약을 최소 3개까지 보강 +- `Input-Artifact`: 산출물 파일 저장 경로 확인 후 재생성 ## 실제 결과 - 입력 요약: -- 요청 목적: +- 문서 제목: +- 작업 목적: - 작업 범위: - 주요 제약: - 확인 필요 사항: +- 충족 항목 수: +- 충족률: +- 실패 분류: +- 수정 액션: ## 판정 - pass / revise / fail @@ -44,3 +78,4 @@ Step 1 / 입력 확인 ## 다음 단계 전달물 - Step 2에서 참고할 입력 요약 - 제약 목록 +- 확인 필요 사항 목록 diff --git a/issues/Step-2-Interpretation.md b/issues/Step-2-Interpretation.md index e4ac9a1..9571f43 100644 --- a/issues/Step-2-Interpretation.md +++ b/issues/Step-2-Interpretation.md @@ -2,40 +2,75 @@ Step 2 / 기준 해석 ## 목적 -입력 문서의 핵심 목적, 의미 보존 기준, 실패 패턴, 검증 기준을 정리한다. +입력 문서의 핵심 목적, 의미 보존 기준, 실패 패턴, 검증 기준을 해석 가능한 형태로 확정한다. ## 입력 - Step 1 결과 경로: - 입력 문서 경로: ## 실행 방법 -1. 입력 요약을 읽는다. -2. 핵심 목적을 한두 문장으로 정리한다. -3. 반드시 보존해야 할 의미를 적는다. -4. 경계해야 할 실패 패턴을 적는다. -5. 검증 기준 초안을 만든다. +1. Step 1 산출물을 읽는다. +2. 아래 `필수 산출 항목` 5개를 작성한다. +3. 각 항목 충족 여부를 체크한다. +4. `판정 규칙`에 따라 pass / revise / fail을 결정한다. +5. 실패 시 `수정 액션`을 기록한다. + +## 필수 산출 항목 +- B1. 핵심 목적 1문장 +- B2. 의미 보존 기준 3개 이상 +- B3. 실패 패턴 3개 이상 +- B4. 검증 기준 3개 이상 +- B5. 핵심 정보 / 보조 정보 구분 각 1개 이상 ## 성공 기준 -- 핵심 목적이 선명하다. -- 보존해야 할 의미가 기록된다. -- 실패 패턴과 검증 기준이 드러난다. +- B1~B5 전부 작성됨 +- 핵심 목적은 1문장으로 끝남 +- 의미 보존 기준, 실패 패턴, 검증 기준이 각각 최소 3개 이상임 +- 핵심/보조 구분이 모두 존재함 ## 실패 기준 -- 목적이 너무 넓거나 모호하다. -- 핵심과 보조가 구분되지 않는다. -- 다음 단계 입력으로 쓰기 어렵다. +- 핵심 목적 미기록 +- 의미 보존 기준 2개 이하 +- 실패 패턴 2개 이하 +- 검증 기준 2개 이하 +- 핵심/보조 구분 누락 + +## KPI / 판정 규칙 +- 충족률 = 충족 항목 수 / 5 +- `pass`: 충족률 100% and 치명 항목(B1, B2, B4) 모두 충족 +- `revise`: 충족률 80% 이상 100% 미만 and 치명 항목 모두 충족 +- `fail`: 충족률 80% 미만 or 치명 항목 1개 이상 누락 ## 실패 분류 -- Interpretation +- `Interpret-Purpose`: 핵심 목적 정의 실패 +- `Interpret-Preserve`: 의미 보존 기준 부족 +- `Interpret-Risk`: 실패 패턴 정의 부족 +- `Interpret-Verify`: 검증 기준 정의 부족 +- `Interpret-Split`: 핵심/보조 구분 실패 + +## 수정 액션 가이드 +- `Interpret-Purpose`: 핵심 목적을 1문장으로 다시 작성 +- `Interpret-Preserve`: 원문에서 반드시 유지할 의미를 최소 3개로 보강 +- `Interpret-Risk`: 오해/왜곡/누락 위험을 최소 3개로 보강 +- `Interpret-Verify`: 이후 검증에서 볼 체크 항목을 최소 3개로 보강 +- `Interpret-Split`: 핵심과 보조 정보를 다시 분리 ## 실제 결과 - 핵심 목적: - 의미 보존 기준: - 실패 패턴: - 검증 기준: +- 핵심 정보: +- 보조 정보: +- 충족 항목 수: +- 충족률: +- 실패 분류: +- 수정 액션: ## 판정 - pass / revise / fail ## 다음 단계 전달물 -- Step 3에서 참고할 해석 결과 +- Step 3에서 사용할 해석 결과 +- 핵심/보조 구분표 +- 검증 기준 초안 diff --git a/issues/Step-3-Content-Structuring.md b/issues/Step-3-Content-Structuring.md index 714865e..d8634fa 100644 --- a/issues/Step-3-Content-Structuring.md +++ b/issues/Step-3-Content-Structuring.md @@ -2,40 +2,74 @@ Step 3 / 콘텐츠 구조화 ## 목적 -원문을 바로 생성하지 않고, 중심 메시지와 보조 정보를 분리해 구조를 정한다. +원문을 바로 생성하지 않고, 중심 메시지와 보조 정보를 분리해 구조와 우선순위를 확정한다. ## 입력 - Step 2 결과 경로: - 입력 문서 경로: ## 실행 방법 -1. 중심 메시지를 정리한다. -2. 보조 정보를 분리한다. -3. 섹션 구조와 우선순위를 정한다. -4. body/sidebar/footer 배치 가정을 적는다. +1. 중심 메시지 1개를 확정한다. +2. 보조 메시지를 분리한다. +3. 섹션 구조를 작성한다. +4. body/sidebar/footer 배치 가정을 작성한다. +5. 중복 여부와 누락 여부를 점검한다. + +## 필수 산출 항목 +- C1. 중심 메시지 1개 +- C2. 보조 메시지 2개 이상 +- C3. 섹션 구조 3~4단계 +- C4. body/sidebar/footer 배치 가정 모두 작성 +- C5. 중복 항목 0개 확인 ## 성공 기준 -- 중심 메시지와 보조 정보가 분리된다. -- 섹션 구조가 드러난다. -- 우선순위와 배치 가정이 있다. +- C1~C5 전부 충족 +- 중심 메시지가 1개로 고정됨 +- 보조 메시지가 최소 2개 이상 존재함 +- 배치 가정이 3개 영역 모두 작성됨 +- 중복 정보가 확인되지 않음 ## 실패 기준 -- 구조 없이 원문 나열 수준이다. -- 핵심 메시지가 묻힌다. -- 정보가 중복되거나 충돌한다. +- 중심 메시지 없음 +- 보조 메시지 1개 이하 +- 섹션 구조 없음 또는 5단계 이상으로 과도함 +- body/sidebar/footer 중 1개 이상 누락 +- 동일 정보가 여러 영역에 중복 배치됨 + +## KPI / 판정 규칙 +- 충족률 = 충족 항목 수 / 5 +- `pass`: 충족률 100% and 치명 항목(C1, C3, C4) 모두 충족 +- `revise`: 충족률 80% 이상 100% 미만 and 치명 항목 모두 충족 +- `fail`: 충족률 80% 미만 or 치명 항목 1개 이상 누락 ## 실패 분류 -- Interpretation -- Planning +- `Structure-Core`: 중심 메시지 설정 실패 +- `Structure-Support`: 보조 메시지 분리 부족 +- `Structure-Section`: 섹션 구조 설계 실패 +- `Structure-Layout`: 영역 배치 가정 실패 +- `Structure-Duplication`: 중복 정보 존재 + +## 수정 액션 가이드 +- `Structure-Core`: 중심 메시지를 1개로 재정의 +- `Structure-Support`: 보조 메시지를 최소 2개 이상 재분리 +- `Structure-Section`: 섹션 구조를 3~4단계로 재정리 +- `Structure-Layout`: 3개 영역 배치 가정을 모두 작성 +- `Structure-Duplication`: 중복 정보 제거 후 영역 재배치 ## 실제 결과 - 중심 메시지: -- 보조 정보: +- 보조 메시지: - 섹션 구조: - 배치 가정: +- 중복 여부: +- 충족 항목 수: +- 충족률: +- 실패 분류: +- 수정 액션: ## 판정 - pass / revise / fail ## 다음 단계 전달물 - Step 4에서 사용할 구조화 결과 +- 영역 배치 가정표 diff --git a/issues/Step-4-Execution-Planning.md b/issues/Step-4-Execution-Planning.md index 6842eaf..a8ee10a 100644 --- a/issues/Step-4-Execution-Planning.md +++ b/issues/Step-4-Execution-Planning.md @@ -2,39 +2,73 @@ Step 4 / 실행 계획 수립 ## 목적 -실제 실행을 어떤 stage 순서로 진행할지 정리하고 검증 및 재시도 기준을 확정한다. +실제 실행을 어떤 stage 순서로 진행할지 정리하고, 검증 및 재시도 기준을 확정한다. ## 입력 - Step 3 결과 경로: - 관련 위키 경로: ## 실행 방법 -1. 필요한 stage를 식별한다. -2. stage별 입력과 출력을 적는다. -3. stage별 검증 포인트를 적는다. +1. 필요한 stage를 나열한다. +2. 각 stage의 입력과 출력을 적는다. +3. 각 stage의 검증 포인트를 적는다. 4. 재시도 기준과 fallback 경로를 적는다. +5. 실행 누락 stage가 없는지 점검한다. + +## 필수 산출 항목 +- D1. stage 목록 1개 이상 +- D2. stage별 입력 정의 100% +- D3. stage별 출력 정의 100% +- D4. stage별 검증 포인트 1개 이상 +- D5. 재시도 기준 명시 +- D6. fallback 경로 명시 ## 성공 기준 -- stage 목록이 명확하다. -- stage별 입력/출력/검증 기준이 있다. -- 재시도와 fallback 경로가 정리된다. +- D1~D6 전부 충족 +- 모든 실행 stage에 입력/출력/검증이 연결됨 +- 재시도 기준과 fallback 경로가 존재함 ## 실패 기준 -- stage가 빠져 있다. -- 검증 없는 생성 단계가 있다. -- 실행 경로가 불명확하다. +- stage 누락 +- 입력/출력 정의 누락 stage 존재 +- 검증 포인트 없는 stage 존재 +- 재시도 기준 누락 +- fallback 경로 누락 + +## KPI / 판정 규칙 +- 충족률 = 충족 항목 수 / 6 +- `pass`: 충족률 100% and 치명 항목(D2, D3, D4) 모두 충족 +- `revise`: 충족률 83% 이상 100% 미만 and 치명 항목 모두 충족 +- `fail`: 충족률 83% 미만 or 치명 항목 1개 이상 누락 ## 실패 분류 -- Planning +- `Plan-Stage`: stage 구성 누락 +- `Plan-IO`: 입력/출력 정의 부족 +- `Plan-Verify`: 검증 포인트 부족 +- `Plan-Retry`: 재시도 기준 누락 +- `Plan-Fallback`: fallback 경로 누락 + +## 수정 액션 가이드 +- `Plan-Stage`: 빠진 stage 추가 +- `Plan-IO`: 누락된 입력/출력 정의 보강 +- `Plan-Verify`: stage별 검증 포인트 추가 +- `Plan-Retry`: 재시도 조건과 횟수 정의 +- `Plan-Fallback`: 대체 경로 명시 ## 실제 결과 - stage 목록: +- stage별 입력/출력: - 검증 포인트: - 재시도 기준: - fallback 경로: +- 충족 항목 수: +- 충족률: +- 실패 분류: +- 수정 액션: ## 판정 - pass / revise / fail ## 다음 단계 전달물 - Step 5에서 사용할 실행 계획 +- stage별 실행 체크리스트 diff --git a/issues/Step-5-Execution.md b/issues/Step-5-Execution.md index c812f7b..4b20930 100644 --- a/issues/Step-5-Execution.md +++ b/issues/Step-5-Execution.md @@ -10,30 +10,59 @@ Step 5 / 실제 수행 ## 실행 방법 1. 계획된 stage를 순서대로 수행한다. -2. 산출물을 저장한다. +2. stage별 산출물을 저장한다. 3. 경고와 재시도 이력을 남긴다. 4. 최종 결과물 경로를 연결한다. +5. 저장 누락과 실행 중단 여부를 점검한다. + +## 필수 산출 항목 +- E1. 실제 실행 경로 기록 +- E2. 산출물 파일 1개 이상 생성 +- E3. 중간 또는 최종 결과 경로 기록 +- E4. 경고 사항 기록 +- E5. 재시도 이력 기록 (없으면 없음으로 표기) ## 성공 기준 -- 산출물이 실제로 생성되었다. -- 실행 경로가 추적 가능하다. -- 경고와 재시도 이력이 남는다. +- E1~E5 전부 작성됨 +- 산출물 파일이 실제로 존재함 +- 실행 경로가 추적 가능함 +- 경고/재시도 이력이 남음 ## 실패 기준 -- 실행이 중간에 끊겼다. -- 산출물이 저장되지 않았다. -- 어떤 입력으로 어떤 실행을 했는지 추적이 안 된다. +- 실행 중단 +- 산출물 미생성 +- 실행 경로 미기록 +- 경고/재시도 이력 미기록 + +## KPI / 판정 규칙 +- 충족률 = 충족 항목 수 / 5 +- `pass`: 충족률 100% and 치명 항목(E1, E2, E3) 모두 충족 +- `revise`: 충족률 80% 이상 100% 미만 and 치명 항목 모두 충족 +- `fail`: 충족률 80% 미만 or 치명 항목 1개 이상 누락 ## 실패 분류 -- Generation -- Rendering -- Tooling +- `Exec-Run`: 실행 중단 +- `Exec-Artifact`: 산출물 생성 실패 +- `Exec-Trace`: 실행 경로 추적 불가 +- `Exec-Warn`: 경고/재시도 기록 누락 +- `Exec-Tool`: 도구/스크립트 문제 + +## 수정 액션 가이드 +- `Exec-Run`: 중단 지점 재확인 후 해당 stage 재실행 +- `Exec-Artifact`: 산출물 경로와 저장 로직 점검 후 재생성 +- `Exec-Trace`: 사용한 스크립트/명령/입력을 다시 기록 +- `Exec-Warn`: 경고와 재시도 이력을 보강 +- `Exec-Tool`: 도구 오류 분리 후 수정 ## 실제 결과 - 사용한 실행 경로: - 생성된 산출물: - 경고: - 재시도 이력: +- 충족 항목 수: +- 충족률: +- 실패 분류: +- 수정 액션: ## 판정 - pass / revise / fail diff --git a/issues/Step-6-Validation-and-Recording.md b/issues/Step-6-Validation-and-Recording.md index d515023..3c68314 100644 --- a/issues/Step-6-Validation-and-Recording.md +++ b/issues/Step-6-Validation-and-Recording.md @@ -14,20 +14,51 @@ Step 6 / 검증 및 기록 3. 렌더링/측정 결과를 평가한다. 4. 최종 판정을 적는다. 5. 다음 액션과 되돌림 지점을 기록한다. +6. 실패 원인을 분류한다. + +## 필수 산출 항목 +- F1. 목적 적합성 평가 +- F2. 내용 보존 평가 +- F3. 렌더링/측정 평가 +- F4. 최종 판정 1개 +- F5. 실패 원인 분류 1개 이상 (실패 시) +- F6. 다음 액션 1개 이상 +- F7. 되돌림 지점 명시 ## 성공 기준 -- 목적 적합성, 내용 보존, 제약 준수, 렌더 상태가 평가되었다. -- 최종 판정이 명시되었다. -- 다음 액션과 되돌림 지점이 기록되었다. +- F1~F7 전부 작성됨 +- 최종 판정이 명확함 +- 실패 시 실패 원인과 수정 방향이 분명함 +- 다음 run으로 넘길 개선 사항이 존재함 ## 실패 기준 -- 검증 결과가 모호하다. -- 실패 원인이 분류되지 않았다. -- 다음 run으로 이어질 개선 포인트가 없다. +- 평가 항목 누락 +- 최종 판정 누락 +- 실패 원인 분류 누락 +- 다음 액션 없음 +- 되돌림 지점 없음 + +## KPI / 판정 규칙 +- 충족률 = 충족 항목 수 / 7 +- `pass`: 충족률 100% and 치명 항목(F1, F2, F3, F4) 모두 충족 +- `revise`: 충족률 86% 이상 100% 미만 and 치명 항목 모두 충족 +- `fail`: 충족률 86% 미만 or 치명 항목 1개 이상 누락 ## 실패 분류 -- Verification -- Quality +- `Verify-Purpose`: 목적 적합성 불충분 +- `Verify-Preserve`: 내용 보존 실패 +- `Verify-Render`: 렌더/측정 실패 +- `Verify-Judgement`: 최종 판정 불명확 +- `Verify-Action`: 다음 액션 부족 +- `Verify-Rollback`: 되돌림 지점 미정 + +## 수정 액션 가이드 +- `Verify-Purpose`: 중심 메시지와 결과물의 일치 여부 재검토 +- `Verify-Preserve`: 누락/과잉 생성/왜곡 항목 보강 +- `Verify-Render`: overflow 또는 배치 문제 수정 +- `Verify-Judgement`: pass/revise/fail 판정 근거를 다시 명시 +- `Verify-Action`: 다음 run 개선 항목을 최소 1개 이상 추가 +- `Verify-Rollback`: 어느 step으로 되돌릴지 명시 ## 실제 결과 - 목적 적합성: @@ -37,6 +68,9 @@ Step 6 / 검증 및 기록 - 실패 원인 분류: - 다음 액션: - 되돌림 지점: +- 충족 항목 수: +- 충족률: +- 수정 액션: ## 판정 - pass / revise / fail