diff --git a/README.md b/README.md index 482d14c..7566b26 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,14 @@ # C.E.L._slide_test -이 저장소는 `design_agent`의 문서화, `Kei API` 비의존 실행 경로 실험, run 단위 산출물 정리를 위한 작업 공간이다. +이 저장소는 슬라이드 생성 작업을 단계별로 해석, 계획, 실행, 검증하고 그 결과를 반복적으로 개선하기 위한 작업 공간이다. ## 구성 -- `docs/`: 방향성 문서, Stage 1 문서, run-001 기록 -- `scripts/`: `Kei API` 없이 후반부 실행을 시도하는 브리지 스크립트 -- `issues/`: Gitea 이슈에 올릴 초안 문서 +- `docs/`: 방향성 문서, Stage 1 문서, run 기록, 실행 결과 +- `scripts/`: 후반부 실행과 실험을 위한 스크립트 +- `issues/`: Gitea 이슈 탭에 등록할 step별 이슈 본문 초안 ## 현재 포함된 항목 -- Stage 1 이해 및 문서화 자료 +- 단계별 운영 문서 - run-001 해석/구조화/계획/검증 기록 -- `run_from_artifacts.py` 브리지 스크립트 +- 실행 결과와 측정 결과 +- 반복 실행을 위한 템플릿 diff --git a/docs/LOOP-PROCESS.md b/docs/LOOP-PROCESS.md index 0c242f9..958dbc5 100644 --- a/docs/LOOP-PROCESS.md +++ b/docs/LOOP-PROCESS.md @@ -1,18 +1,19 @@ # Loop Process ## 목적 -이 문서는 `design_agent` 작업을 run 단위로 반복 실행하면서, 각 단계의 성공과 실패를 평가하고, 그 결과를 이슈와 다음 run으로 연결하는 운영 규칙을 정의한다. +이 문서는 슬라이드 생성 작업을 run 단위로 반복 실행하면서, 각 단계의 성공과 실패를 평가하고, 그 결과를 이슈와 다음 run으로 연결하는 운영 규칙을 정의한다. ## 기본 원칙 - 모든 작업은 `run-001`, `run-002`처럼 run 단위로 수행한다. - 모든 run은 `01-input`부터 `06-validation`까지 같은 구조를 따른다. - 각 단계는 단순 수행만이 아니라 `성공/실패 평가`를 포함해야 한다. - 검증 결과는 끝이 아니라 다음 run의 입력이 된다. +- 실제 Gitea 이슈는 step 단위로 관리한다. ## 표준 루프 1. 입력 준비 2. Step 1 입력 확인 -3. Step 2 Kei 기준 해석 +3. Step 2 기준 해석 4. Step 3 콘텐츠 구조화 5. Step 4 실행 계획 수립 6. Step 5 실제 수행 @@ -35,7 +36,7 @@ 실패 분류: - Input -### Step 2 Kei 기준 해석 +### Step 2 기준 해석 성공 기준: - 핵심 목적이 한두 문장으로 정리되었다. - 반드시 지켜야 할 의미가 기록되었다. @@ -73,7 +74,7 @@ 실패 기준: - 세부 stage가 생략되었다. - 검증 없는 생성 단계가 있다. -- Kei API 의존 여부가 불명확하다. +- 실행 경로가 불명확하다. 실패 분류: - Planning @@ -81,13 +82,13 @@ ### Step 5 실제 수행 성공 기준: - run 산출물이 실제로 생성되었다. -- 필요한 경우 기존 코드 자산이 사용되었다. +- 필요한 코드나 스크립트가 사용되었다. - 실패한 stage와 재시도 이력이 남는다. 실패 기준: - 실행이 중간에 끊겼다. - 산출물이 저장되지 않았다. -- 어떤 입력으로 어떤 코드를 돌렸는지 추적이 안 된다. +- 어떤 입력으로 어떤 실행을 했는지 추적이 안 된다. 실패 분류: - Generation @@ -120,8 +121,8 @@ - Tooling ## 이슈 운영 원칙 -- 각 run은 최소 1개의 이슈 요약을 남긴다. -- 이슈에는 step별 결과 요약, 판정, 실패 원인, 다음 액션을 적는다. +- 각 step은 실제 Gitea 이슈 탭에서 개별 이슈로 관리한다. +- 각 step 이슈에는 목적, 입력, 실행 방법, 성공 기준, 실패 기준, 실제 결과, 판정, 다음 단계 전달물을 포함한다. - 자세한 산출물은 저장소 경로로 연결한다. ## 다음 run 연결 규칙 diff --git a/issues/README.md b/issues/README.md new file mode 100644 index 0000000..aae5962 --- /dev/null +++ b/issues/README.md @@ -0,0 +1,22 @@ +# Step Issue Usage + +이 폴더의 문서들은 코드에 넣기 위한 문서가 아니라, Gitea `이슈` 탭에 그대로 붙여 넣기 위한 step별 이슈 본문 초안이다. + +## 생성 순서 +1. Step 1 이슈 생성 +2. Step 2 이슈 생성 +3. Step 3 이슈 생성 +4. Step 4 이슈 생성 +5. Step 5 이슈 생성 +6. Step 6 이슈 생성 + +## 각 이슈에 반드시 들어갈 항목 +- 목적 +- 입력 +- 실행 방법 +- 성공 기준 +- 실패 기준 +- 실패 분류 +- 실제 결과 +- 판정 +- 다음 단계 전달물 diff --git a/issues/Step-1-Input-Review.md b/issues/Step-1-Input-Review.md new file mode 100644 index 0000000..b811189 --- /dev/null +++ b/issues/Step-1-Input-Review.md @@ -0,0 +1,46 @@ +## 제목 +Step 1 / 입력 확인 + +## 목적 +현재 입력 문서를 읽고 작업 목적, 범위, 제약을 명확히 한다. + +## 입력 +- 입력 폴더: +- 입력 파일명: +- 입력 파일 경로: +- 관련 산출물 경로: + +## 실행 방법 +1. 입력 문서를 읽는다. +2. 요청 목적을 정리한다. +3. 작업 범위를 정리한다. +4. 주요 제약을 정리한다. +5. 확인이 필요한 항목을 남긴다. + +## 성공 기준 +- 입력 파일이 명확히 식별된다. +- 요청 목적이 정리된다. +- 작업 범위가 정리된다. +- 주요 제약이 기록된다. + +## 실패 기준 +- 입력 파일이 불명확하다. +- 목적이 모호하다. +- 제약이 누락되었다. + +## 실패 분류 +- Input + +## 실제 결과 +- 입력 요약: +- 요청 목적: +- 작업 범위: +- 주요 제약: +- 확인 필요 사항: + +## 판정 +- pass / revise / fail + +## 다음 단계 전달물 +- Step 2에서 참고할 입력 요약 +- 제약 목록 diff --git a/issues/Step-2-Interpretation.md b/issues/Step-2-Interpretation.md new file mode 100644 index 0000000..e4ac9a1 --- /dev/null +++ b/issues/Step-2-Interpretation.md @@ -0,0 +1,41 @@ +## 제목 +Step 2 / 기준 해석 + +## 목적 +입력 문서의 핵심 목적, 의미 보존 기준, 실패 패턴, 검증 기준을 정리한다. + +## 입력 +- Step 1 결과 경로: +- 입력 문서 경로: + +## 실행 방법 +1. 입력 요약을 읽는다. +2. 핵심 목적을 한두 문장으로 정리한다. +3. 반드시 보존해야 할 의미를 적는다. +4. 경계해야 할 실패 패턴을 적는다. +5. 검증 기준 초안을 만든다. + +## 성공 기준 +- 핵심 목적이 선명하다. +- 보존해야 할 의미가 기록된다. +- 실패 패턴과 검증 기준이 드러난다. + +## 실패 기준 +- 목적이 너무 넓거나 모호하다. +- 핵심과 보조가 구분되지 않는다. +- 다음 단계 입력으로 쓰기 어렵다. + +## 실패 분류 +- Interpretation + +## 실제 결과 +- 핵심 목적: +- 의미 보존 기준: +- 실패 패턴: +- 검증 기준: + +## 판정 +- pass / revise / fail + +## 다음 단계 전달물 +- Step 3에서 참고할 해석 결과 diff --git a/issues/Step-3-Content-Structuring.md b/issues/Step-3-Content-Structuring.md new file mode 100644 index 0000000..714865e --- /dev/null +++ b/issues/Step-3-Content-Structuring.md @@ -0,0 +1,41 @@ +## 제목 +Step 3 / 콘텐츠 구조화 + +## 목적 +원문을 바로 생성하지 않고, 중심 메시지와 보조 정보를 분리해 구조를 정한다. + +## 입력 +- Step 2 결과 경로: +- 입력 문서 경로: + +## 실행 방법 +1. 중심 메시지를 정리한다. +2. 보조 정보를 분리한다. +3. 섹션 구조와 우선순위를 정한다. +4. body/sidebar/footer 배치 가정을 적는다. + +## 성공 기준 +- 중심 메시지와 보조 정보가 분리된다. +- 섹션 구조가 드러난다. +- 우선순위와 배치 가정이 있다. + +## 실패 기준 +- 구조 없이 원문 나열 수준이다. +- 핵심 메시지가 묻힌다. +- 정보가 중복되거나 충돌한다. + +## 실패 분류 +- Interpretation +- Planning + +## 실제 결과 +- 중심 메시지: +- 보조 정보: +- 섹션 구조: +- 배치 가정: + +## 판정 +- pass / revise / fail + +## 다음 단계 전달물 +- Step 4에서 사용할 구조화 결과 diff --git a/issues/Step-4-Execution-Planning.md b/issues/Step-4-Execution-Planning.md new file mode 100644 index 0000000..6842eaf --- /dev/null +++ b/issues/Step-4-Execution-Planning.md @@ -0,0 +1,40 @@ +## 제목 +Step 4 / 실행 계획 수립 + +## 목적 +실제 실행을 어떤 stage 순서로 진행할지 정리하고 검증 및 재시도 기준을 확정한다. + +## 입력 +- Step 3 결과 경로: +- 관련 위키 경로: + +## 실행 방법 +1. 필요한 stage를 식별한다. +2. stage별 입력과 출력을 적는다. +3. stage별 검증 포인트를 적는다. +4. 재시도 기준과 fallback 경로를 적는다. + +## 성공 기준 +- stage 목록이 명확하다. +- stage별 입력/출력/검증 기준이 있다. +- 재시도와 fallback 경로가 정리된다. + +## 실패 기준 +- stage가 빠져 있다. +- 검증 없는 생성 단계가 있다. +- 실행 경로가 불명확하다. + +## 실패 분류 +- Planning + +## 실제 결과 +- stage 목록: +- 검증 포인트: +- 재시도 기준: +- fallback 경로: + +## 판정 +- pass / revise / fail + +## 다음 단계 전달물 +- Step 5에서 사용할 실행 계획 diff --git a/issues/Step-5-Execution.md b/issues/Step-5-Execution.md new file mode 100644 index 0000000..c812f7b --- /dev/null +++ b/issues/Step-5-Execution.md @@ -0,0 +1,42 @@ +## 제목 +Step 5 / 실제 수행 + +## 목적 +계획에 따라 실제 실행을 수행하고 산출물을 저장한다. + +## 입력 +- Step 4 결과 경로: +- 실행에 사용할 코드/스크립트: + +## 실행 방법 +1. 계획된 stage를 순서대로 수행한다. +2. 산출물을 저장한다. +3. 경고와 재시도 이력을 남긴다. +4. 최종 결과물 경로를 연결한다. + +## 성공 기준 +- 산출물이 실제로 생성되었다. +- 실행 경로가 추적 가능하다. +- 경고와 재시도 이력이 남는다. + +## 실패 기준 +- 실행이 중간에 끊겼다. +- 산출물이 저장되지 않았다. +- 어떤 입력으로 어떤 실행을 했는지 추적이 안 된다. + +## 실패 분류 +- Generation +- Rendering +- Tooling + +## 실제 결과 +- 사용한 실행 경로: +- 생성된 산출물: +- 경고: +- 재시도 이력: + +## 판정 +- pass / revise / fail + +## 다음 단계 전달물 +- Step 6에서 사용할 실행 결과와 산출물 경로 diff --git a/issues/Step-6-Validation-and-Recording.md b/issues/Step-6-Validation-and-Recording.md new file mode 100644 index 0000000..d515023 --- /dev/null +++ b/issues/Step-6-Validation-and-Recording.md @@ -0,0 +1,45 @@ +## 제목 +Step 6 / 검증 및 기록 + +## 목적 +최종 결과가 목적과 제약에 맞는지 검증하고, 다음 run을 위한 개선 방향을 기록한다. + +## 입력 +- Step 5 결과 경로: +- 최종 산출물 경로: + +## 실행 방법 +1. 목적 적합성을 평가한다. +2. 내용 보존을 평가한다. +3. 렌더링/측정 결과를 평가한다. +4. 최종 판정을 적는다. +5. 다음 액션과 되돌림 지점을 기록한다. + +## 성공 기준 +- 목적 적합성, 내용 보존, 제약 준수, 렌더 상태가 평가되었다. +- 최종 판정이 명시되었다. +- 다음 액션과 되돌림 지점이 기록되었다. + +## 실패 기준 +- 검증 결과가 모호하다. +- 실패 원인이 분류되지 않았다. +- 다음 run으로 이어질 개선 포인트가 없다. + +## 실패 분류 +- Verification +- Quality + +## 실제 결과 +- 목적 적합성: +- 내용 보존: +- 렌더링/측정: +- 최종 판정: +- 실패 원인 분류: +- 다음 액션: +- 되돌림 지점: + +## 판정 +- pass / revise / fail + +## 다음 단계 전달물 +- 다음 run 시작 전에 참고할 검증 결과와 개선 사항 diff --git a/issues/run-001-issue-body.md b/issues/run-001-issue-body.md deleted file mode 100644 index 9e909cd..0000000 --- a/issues/run-001-issue-body.md +++ /dev/null @@ -1,66 +0,0 @@ -# run-001 Issue Body - -## 제목 -run-001 - 건설산업 DX의 올바른 이해(0127) / Kei API 없이 후반부 실행 실험 - -## 입력 -- 파일: `01. 건설산업 DX의 올바른 이해(0127).mdx` -- 목표: DX와 BIM의 혼용 문제를 바로잡고, `DX는 상위 개념`, `BIM은 핵심 기술`이라는 메시지를 1장 슬라이드로 전달 - -## Step 1 입력 확인 -- 결과 문서: `docs/run-001/01-input/input-review.md` -- 판정: `pass` -- 요약: 입력 목적, 보존 요소, 제약사항을 정리했고 이미지/비교표 처리는 후속 단계에서 결정 대상으로 남김 - -## Step 2 Kei 기준 해석 -- 결과 문서: `docs/run-001/02-kei-interpretation/kei-interpretation.md` -- 판정: `pass` -- 요약: 핵심 목적을 `DX는 상위 개념, BIM은 핵심 기술`로 고정했고, 비교표와 사례는 보조 정보로 다루는 기준을 정함 - -## Step 3 콘텐츠 구조화 -- 결과 문서: `docs/run-001/03-structure/content-structure.md` -- 판정: `pass` -- 요약: `문제 제기 -> 정의 -> 관계 설명 -> 결론` 구조로 정리하고, body/sidebar/footer 배치 가정을 설정함 - -## Step 4 실행 계획 -- 결과 문서: `docs/run-001/04-plan/execution-plan.md` -- Stage 1A/1B 대체 입력: - - `docs/run-001/04-plan/stage-1a-topics.json` - - `docs/run-001/04-plan/stage-1b-refined-concepts.json` -- 판정: `pass` -- 요약: `Phase T` 전체 stage를 따르되, 초기 해석은 run 산출물 기반, 후반부는 기존 `design_agent` 코드 자산 기반으로 연결하는 계획 수립 - -## Step 5 실제 수행 -- 브리지 스크립트: `scripts/run_from_artifacts.py` -- 실행 산출물: - - `docs/run-001/05-execution/final.html` - - `docs/run-001/05-execution/generated_html.json` - - `docs/run-001/05-execution/measurement.json` - - `docs/run-001/05-execution/context.json` -- 판정: `pass` -- 요약: `Kei API` 없이도 후반부 실행 경로를 실제로 동작시켰고 HTML 결과물까지 생성함 - -## Step 6 검증 및 기록 -- 결과 문서: `docs/run-001/06-validation/validation-result.md` -- 판정: `revise` -- 요약: - - 실행 경로 검증: 통과 - - 렌더링/측정: 통과 - - 내용 보존 검증: 실패 - - 최종 품질 판정: 재작업 필요 - -## 핵심 실패 원인 -- `content_verifier` 기준으로 `body_core`에서 이미지 참조와 비교표 일부가 누락으로 검출됨 -- 생성 전략은 비교표를 요약형으로 압축했지만, 검증 기준은 원문 세부 보존을 더 강하게 요구함 -- 따라서 `Stage 1A/1B 산출물`과 `검증 규칙` 사이에 정합성 문제가 있음 - -## 현황 -- `Kei API`를 기본 경로에서 빼고도 후반부 실행이 가능하다는 점은 확인함 -- 즉, 구조 전환 실험은 성공 -- 다만 결과물 품질과 verifier 정합성은 아직 보정 필요 - -## 개선 방향 -1. `Stage 1A/1B` 산출물에서 비교표와 이미지 참조 처리 방식을 더 명확히 적기 -2. `Stage 2` 생성 전략을 `핵심 메시지 + 핵심 비교축 요약` 기준으로 더 명시하기 -3. 필요 시 `content_verifier`를 run 기반 구조화 흐름에 맞게 분기 또는 완화하기 -4. 다음 run에서 동일 실패 패턴이 재현되는지 비교 검증하기 diff --git a/issues/run-001.md b/issues/run-001.md deleted file mode 100644 index d15327e..0000000 --- a/issues/run-001.md +++ /dev/null @@ -1,41 +0,0 @@ -# run-001 Issue Draft - -## 제목 -run-001 - 건설산업 DX의 올바른 이해(0127) / Kei API 없이 후반부 실행 실험 - -## 입력 -- 파일: `01. 건설산업 DX의 올바른 이해(0127).mdx` -- 목적: DX와 BIM의 혼용 문제를 바로잡고, DX는 상위 개념이고 BIM은 핵심 기술이라는 메시지를 1장 슬라이드로 전달 - -## Step 1 입력 확인 결과 -- `docs/run-001/01-input/input-review.md` 참고 - -## Step 2 Kei 기준 해석 결과 -- `docs/run-001/02-kei-interpretation/kei-interpretation.md` 참고 - -## Step 3 콘텐츠 구조화 결과 -- `docs/run-001/03-structure/content-structure.md` 참고 - -## Step 4 실행 계획 -- `docs/run-001/04-plan/execution-plan.md` 참고 -- Stage 1A/1B 대체 입력: - - `docs/run-001/04-plan/stage-1a-topics.json` - - `docs/run-001/04-plan/stage-1b-refined-concepts.json` - -## 실행 경로 -- `scripts/run_from_artifacts.py` 사용 -- `Kei API` 없이 run 산출물을 입력으로 사용 -- 후반부는 기존 `design_agent` 코드 자산 활용 - -## 검증 결과 -- `docs/run-001/06-validation/validation-result.md` 참고 -- 요약: - - 실행 경로 검증: 통과 - - 렌더링/측정: 통과 - - 내용 보존 검증: 실패 - - 최종 판정: revise - -## 다음 액션 -1. Stage 1A/1B 산출물 정교화 -2. 비교표/이미지 처리 방식 명시 강화 -3. 필요 시 verifier 규칙 조정