diff --git a/docs/LOOP-PROCESS.md b/docs/LOOP-PROCESS.md new file mode 100644 index 0000000..0c242f9 --- /dev/null +++ b/docs/LOOP-PROCESS.md @@ -0,0 +1,130 @@ +# Loop Process + +## 목적 +이 문서는 `design_agent` 작업을 run 단위로 반복 실행하면서, 각 단계의 성공과 실패를 평가하고, 그 결과를 이슈와 다음 run으로 연결하는 운영 규칙을 정의한다. + +## 기본 원칙 +- 모든 작업은 `run-001`, `run-002`처럼 run 단위로 수행한다. +- 모든 run은 `01-input`부터 `06-validation`까지 같은 구조를 따른다. +- 각 단계는 단순 수행만이 아니라 `성공/실패 평가`를 포함해야 한다. +- 검증 결과는 끝이 아니라 다음 run의 입력이 된다. + +## 표준 루프 +1. 입력 준비 +2. Step 1 입력 확인 +3. Step 2 Kei 기준 해석 +4. Step 3 콘텐츠 구조화 +5. Step 4 실행 계획 수립 +6. Step 5 실제 수행 +7. Step 6 검증 및 기록 +8. 이슈 업데이트 +9. 다음 run 반영 + +## 단계별 평가 원칙 +### Step 1 입력 확인 +성공 기준: +- 입력 파일이 명확하다. +- 요청 목적과 작업 범위가 정리되었다. +- 주요 제약이 드러난다. + +실패 기준: +- 입력 파일이 누락되었다. +- 요청 목적이 모호하다. +- 필수 제약이 기록되지 않았다. + +실패 분류: +- Input + +### Step 2 Kei 기준 해석 +성공 기준: +- 핵심 목적이 한두 문장으로 정리되었다. +- 반드시 지켜야 할 의미가 기록되었다. +- 실패 패턴과 검증 기준이 드러난다. + +실패 기준: +- 목적이 너무 넓거나 모호하다. +- 핵심과 보조 정보가 구분되지 않는다. +- 해석 결과가 다음 단계 입력으로 쓰기 어렵다. + +실패 분류: +- Interpretation + +### Step 3 콘텐츠 구조화 +성공 기준: +- 중심 메시지와 보조 정보가 분리되었다. +- 섹션 구조와 우선순위가 드러난다. +- body/sidebar/footer 배치 가정이 있다. + +실패 기준: +- 구조 없이 원문 나열 수준이다. +- 핵심 메시지가 묻힌다. +- 정보가 중복되거나 충돌한다. + +실패 분류: +- Interpretation +- Planning + +### Step 4 실행 계획 수립 +성공 기준: +- Stage 목록이 명확하다. +- stage별 입력, 출력, 검증 기준이 있다. +- 재시도 기준과 fallback 경로가 정리되었다. + +실패 기준: +- 세부 stage가 생략되었다. +- 검증 없는 생성 단계가 있다. +- Kei API 의존 여부가 불명확하다. + +실패 분류: +- Planning + +### Step 5 실제 수행 +성공 기준: +- run 산출물이 실제로 생성되었다. +- 필요한 경우 기존 코드 자산이 사용되었다. +- 실패한 stage와 재시도 이력이 남는다. + +실패 기준: +- 실행이 중간에 끊겼다. +- 산출물이 저장되지 않았다. +- 어떤 입력으로 어떤 코드를 돌렸는지 추적이 안 된다. + +실패 분류: +- Generation +- Rendering +- Tooling + +### Step 6 검증 및 기록 +성공 기준: +- 목적 적합성, 내용 보존, 제약 준수, 렌더 상태가 평가되었다. +- 최종 판정(pass/revise/fail)이 명시되었다. +- 다음 액션과 되돌림 지점이 기록되었다. + +실패 기준: +- 검증 결과가 모호하다. +- 실패 원인이 분류되지 않았다. +- 다음 run으로 이어질 개선 포인트가 없다. + +실패 분류: +- Verification +- Quality + +## 실패 원인 분류 체계 +- Input +- Interpretation +- Planning +- Generation +- Verification +- Rendering +- Quality +- Tooling + +## 이슈 운영 원칙 +- 각 run은 최소 1개의 이슈 요약을 남긴다. +- 이슈에는 step별 결과 요약, 판정, 실패 원인, 다음 액션을 적는다. +- 자세한 산출물은 저장소 경로로 연결한다. + +## 다음 run 연결 규칙 +- 이전 run의 `06-validation` 결과를 다음 run의 참고 입력으로 둔다. +- 같은 실패가 반복되면 verifier 또는 stage 산출물 형식을 수정한다. +- 다음 run 시작 전에 이전 run의 `Next Action`을 반드시 읽는다. diff --git a/docs/RUN-CHECKLIST.md b/docs/RUN-CHECKLIST.md new file mode 100644 index 0000000..5bc79e0 --- /dev/null +++ b/docs/RUN-CHECKLIST.md @@ -0,0 +1,48 @@ +# Run Checklist + +## 새 run 시작 전 +- [ ] 이전 run의 `06-validation`을 읽었다. +- [ ] 이번 run id를 정했다. +- [ ] `docs/run-template`를 복사해 새 run 폴더를 만들었다. + +## Step 1 입력 확인 +- [ ] 입력 파일을 `01-input`에 넣었다. +- [ ] 요청 목적을 적었다. +- [ ] 주요 제약을 적었다. +- [ ] 성공/실패를 판정했다. + +## Step 2 Kei 기준 해석 +- [ ] 핵심 목적을 정리했다. +- [ ] 의미 보존 기준을 적었다. +- [ ] 실패 패턴을 적었다. +- [ ] 성공/실패를 판정했다. + +## Step 3 콘텐츠 구조화 +- [ ] 중심 메시지를 정리했다. +- [ ] 보조 정보와 구분했다. +- [ ] 영역 배치 가정을 적었다. +- [ ] 성공/실패를 판정했다. + +## Step 4 실행 계획 +- [ ] stage 목록을 적었다. +- [ ] 검증 포인트를 적었다. +- [ ] retry/fallback 경로를 적었다. +- [ ] 성공/실패를 판정했다. + +## Step 5 실행 +- [ ] 산출물을 `05-execution`에 저장했다. +- [ ] 사용한 코드/스크립트를 적었다. +- [ ] 경고와 재시도 이력을 적었다. +- [ ] 성공/실패를 판정했다. + +## Step 6 검증 +- [ ] 목적 적합성을 평가했다. +- [ ] 내용 보존을 평가했다. +- [ ] 렌더/측정을 평가했다. +- [ ] 최종 판정(pass/revise/fail)을 적었다. +- [ ] 다음 액션을 적었다. + +## 이슈 업데이트 +- [ ] step별 요약을 이슈 초안에 반영했다. +- [ ] 실패 원인 분류를 적었다. +- [ ] 다음 run 개선 방향을 적었다. diff --git a/docs/run-template/01-input/README.md b/docs/run-template/01-input/README.md new file mode 100644 index 0000000..8c58179 --- /dev/null +++ b/docs/run-template/01-input/README.md @@ -0,0 +1,12 @@ +# Step 1 Input Template + +## Input +- file: +- source path: +- request: +- constraints: + +## Evaluation +- judgement: pass / revise / fail +- reason: +- failure category: diff --git a/docs/run-template/02-kei-interpretation/README.md b/docs/run-template/02-kei-interpretation/README.md new file mode 100644 index 0000000..91a0b1a --- /dev/null +++ b/docs/run-template/02-kei-interpretation/README.md @@ -0,0 +1,12 @@ +# Step 2 Interpretation Template + +## Interpretation +- core purpose: +- preserve meaning: +- risks: +- validation criteria: + +## Evaluation +- judgement: pass / revise / fail +- reason: +- failure category: diff --git a/docs/run-template/03-structure/README.md b/docs/run-template/03-structure/README.md new file mode 100644 index 0000000..35ebacf --- /dev/null +++ b/docs/run-template/03-structure/README.md @@ -0,0 +1,12 @@ +# Step 3 Structure Template + +## Structure +- primary message: +- support message: +- section structure: +- area assumptions: + +## Evaluation +- judgement: pass / revise / fail +- reason: +- failure category: diff --git a/docs/run-template/04-plan/README.md b/docs/run-template/04-plan/README.md new file mode 100644 index 0000000..319c0ce --- /dev/null +++ b/docs/run-template/04-plan/README.md @@ -0,0 +1,16 @@ +# Step 4 Plan Template + +## Stage Plan +1. +2. +3. + +## Validation / Retry +- validation points: +- retry rules: +- fallback path: + +## Evaluation +- judgement: pass / revise / fail +- reason: +- failure category: diff --git a/docs/run-template/05-execution/README.md b/docs/run-template/05-execution/README.md new file mode 100644 index 0000000..a23dec7 --- /dev/null +++ b/docs/run-template/05-execution/README.md @@ -0,0 +1,12 @@ +# Step 5 Execution Template + +## Execution +- used script / code path: +- outputs: +- warnings: +- retries: + +## Evaluation +- judgement: pass / revise / fail +- reason: +- failure category: diff --git a/docs/run-template/06-validation/README.md b/docs/run-template/06-validation/README.md new file mode 100644 index 0000000..8ca6965 --- /dev/null +++ b/docs/run-template/06-validation/README.md @@ -0,0 +1,19 @@ +# Step 6 Validation Template + +## Validation +- purpose fit: +- meaning preservation: +- rendering: +- quality: +- final decision: pass / revise / fail + +## Next Action +1. +2. +3. + +## Evaluation +- judgement: +- reason: +- failure category: +- rollback point: diff --git a/docs/run-template/README.md b/docs/run-template/README.md new file mode 100644 index 0000000..794c2bb --- /dev/null +++ b/docs/run-template/README.md @@ -0,0 +1,16 @@ +# Run Template + +이 폴더는 새 run을 만들 때 그대로 복사하는 템플릿이다. + +## 구조 +- `01-input` +- `02-kei-interpretation` +- `03-structure` +- `04-plan` +- `05-execution` +- `06-validation` + +## 규칙 +- 각 단계는 결과 파일 + 판정 메모를 남긴다. +- 성공/실패 판정은 생략하지 않는다. +- 다음 run 반영 사항은 반드시 `06-validation`에 남긴다. diff --git a/issues/ISSUE-TEMPLATE.md b/issues/ISSUE-TEMPLATE.md new file mode 100644 index 0000000..4a00bfe --- /dev/null +++ b/issues/ISSUE-TEMPLATE.md @@ -0,0 +1,55 @@ +# Issue Template + +## 제목 +run-XXX - [입력 제목] / [핵심 목적] + +## 입력 +- 파일: +- 목적: +- 제약: + +## Step 1 입력 확인 +- 결과 요약: +- 판정: pass / revise / fail +- 실패 원인 분류: + +## Step 2 Kei 기준 해석 +- 결과 요약: +- 판정: pass / revise / fail +- 실패 원인 분류: + +## Step 3 콘텐츠 구조화 +- 결과 요약: +- 판정: pass / revise / fail +- 실패 원인 분류: + +## Step 4 실행 계획 +- 결과 요약: +- 판정: pass / revise / fail +- 실패 원인 분류: + +## Step 5 실제 수행 +- 실행 경로: +- 산출물 경로: +- 판정: pass / revise / fail +- 실패 원인 분류: + +## Step 6 검증 및 기록 +- 검증 결과 요약: +- 최종 판정: pass / revise / fail +- 실패 원인 분류: + +## 현황 정리 +- 현재 상태: +- 핵심 문제: +- 유지할 것: + +## 개선 방향 +1. +2. +3. + +## 다음 run 반영 사항 +- +- +-