Kyeongmin/C.E.L._slide_test
1
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity
23 Commits 1 Branch 0 Tags
37ae72a63effef884618d33fba71c5d8b3c1bfbb
Go to file
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE

README.md

C.E.L._slide_test

이 저장소는 mdx 문서를 읽고 슬라이드 HTML 결과물로 변환하는 전체 실행 프로세스를 관리하기 위한 작업 저장소다.

핵심 목표는 다음과 같다.

  • 누구라도 같은 저장소 구조와 위키 기준만으로 mdx -> 슬라이드 변환을 수행할 수 있어야 한다.
  • 실행 과정은 위키 -> 이슈 -> docs/run-xxx -> 결과물 순서로 추적 가능해야 한다.
  • 결과는 한 번 만들고 끝나는 것이 아니라, 검증 -> revise -> rollback -> 재실행 루프로 개선 가능해야 한다.
  • Codex와 Gitea를 함께 사용해 작업 기준, 실행 기록, 산출물, 검증 결과를 모두 남긴다.

저장소 역할

이 저장소는 단순 코드 저장소가 아니다. 아래 네 가지 역할을 함께 가진다.

  1. 입력과 산출물 저장소
  • mdx 원문 입력
  • 중간 구조화 결과
  • stage snapshot
  • 최종 HTML 결과물
  • 검증 기록
  1. 실행 운영 저장소
  • Step 1 ~ Step 6 이슈 정의
  • stage 기반 실행 스크립트
  • 자동 루프 스크립트
  • Gitea 이슈 코멘트 자동 등록 스크립트
  1. 반복 개선 저장소
  • 실패 분류
  • 수정 액션
  • retry-plan.json
  • rollback 이력
  • 다음 반복에 반영할 개선 방향
  1. 협업 저장소
  • 위키에는 기준과 절차를 둔다.
  • 이슈에는 단계별 실행 지시와 코멘트를 둔다.
  • docs/run-xxx에는 실제 작업 기록과 결과를 둔다.

전체 구조

  • docs/
    • run별 입력, 중간 산출물, stage snapshot, 최종 결과물, 검증 결과
  • scripts/
    • 실제 실행, 자동 루프, Gitea 이슈 코멘트 등록 스크립트
  • issues/
    • Gitea 이슈 탭에 등록할 Step 1 ~ Step 6 본문 초안

주요 경로:

  • docs/run-001/01-input/
  • docs/run-001/02-kei-interpretation/
  • docs/run-001/03-structure/
  • docs/run-001/04-plan/
  • docs/run-001/05-execution/
  • docs/run-001/06-validation/

위키, 이슈, docs의 역할 분리

위키

위키는 기준서다.

위키에서 관리하는 내용:

  • 사고방식과 운영 원칙
  • 상위 작업 절차
  • 상세 파이프라인
  • 실행 프롬프트

즉, 위키는 어떻게 할 것인가를 정의한다.

이슈

이슈는 실행 단위다.

이슈에서 관리하는 내용:

  • Step 1 입력 확인
  • Step 2 기준 해석
  • Step 3 콘텐츠 구조화
  • Step 4 실행 계획
  • Step 5 실제 수행
  • Step 6 검증 및 기록

즉, 이슈는 이번 step에서 무엇을 할 것인가와 실행 후 무엇이 나왔는가를 관리한다.

docs/run-xxx

docs/run-xxx는 실제 작업 기록과 산출물 저장소다.

여기에는 다음이 들어간다.

  • 원본 입력 mdx
  • 중간 해석 파일
  • 계획 파일
  • stage context snapshot
  • 생성 HTML
  • measurement 결과
  • validation 결과
  • 이슈 코멘트 원문

즉, docs/run-xxx는 실제로 무엇이 만들어졌는가와 어느 stage에서 무엇이 바뀌었는가를 저장한다.

실행 대상 입력

각 run은 반드시 원본 입력 파일을 01-input에 함께 둔다.

예시:

  • docs/run-001/01-input/01. 건설산업 DX의 올바른 이해(0127).mdx

이 원칙이 중요한 이유:

  • run만 보면 입력부터 결과까지 모두 추적 가능해야 한다.
  • 외부 경로를 다시 찾지 않아도 재실행이 가능해야 한다.

기본 실행 흐름

전체 흐름은 다음과 같다.

  1. 위키의 Prompt를 읽는다.
  2. Step 이슈를 읽는다.
  3. docs/run-xxx/01-input의 원본 mdx를 입력으로 사용한다.
  4. Step 1 ~ Step 4 결과를 기준으로 실행 준비를 마친다.
  5. scripts/run_from_artifacts.py로 실제 stage 실행을 수행한다.
  6. scripts/auto_loop_runner.py로 검증, retry-plan 생성, rollback, 반복 실행을 수행한다.
  7. 결과를 docs/run-xxx/05-execution, 06-validation에 저장한다.
  8. Step 5, Step 6 결과를 Gitea 이슈 코멘트로 남긴다.

Step 정의

Step 1. 입력 확인

  • 입력 문서를 식별한다.
  • 문서 제목, 목적, 범위, 제약을 정리한다.
  • 결과는 01-input/input-review.md에 남긴다.

Step 2. 기준 해석

  • 입력을 슬라이드 목적에 맞게 해석한다.
  • 핵심 메시지, 보존 기준, 실패 패턴을 정리한다.
  • 결과는 02-kei-interpretation/에 남긴다.

Step 3. 콘텐츠 구조화

  • 중심 메시지와 보조 정보를 구분한다.
  • 본문, 사이드, 결론의 배치 가정을 세운다.
  • 결과는 03-structure/에 남긴다.

Step 4. 실행 계획

  • 실제 stage 실행 계획을 세운다.
  • Stage 1A/1B 산출물, 실행 입력, 검증 포인트를 정리한다.
  • 결과는 04-plan/에 남긴다.

Step 5. 실제 수행

  • 실제 HTML 생성과 렌더링, 측정을 수행한다.
  • stage snapshot과 산출물은 05-execution/에 남긴다.

Step 6. 검증 및 기록

  • 핵심 메시지 가시성, 비교 정보, 이미지 참조, overflow 여부를 검증한다.
  • 실패 시 retry-plan과 rollback 기준을 만든다.
  • 결과는 06-validation/에 남긴다.

stage snapshot

run_from_artifacts.py는 실행 중간 상태를 stage별로 저장한다.

예시:

  • stage_0_context.json
  • stage_1a_context.json
  • stage_1b_context.json
  • stage_1_5a_context.json
  • stage_1_7_context.json
  • stage_1_5b_context.json
  • stage_2_context.json
  • stage_2_verification.json
  • stage_3_context.json
  • stage_4_context.json
  • final_context.json

이 구조가 중요한 이유:

  • 최종 final.html만 보고 수정하지 않는다.
  • 실패가 나면 어느 stage로 돌아가야 하는지 추적할 수 있다.
  • 무한 루프에 가까운 반복 개선의 근거가 된다.

자동 루프

이 저장소의 핵심은 한 번 생성하고 끝나는 것이 아니라, 실패 시 자동으로 보정하고 다시 실행하는 루프다.

현재 자동 루프 스크립트:

  • scripts/auto_loop_runner.py

이 스크립트가 하는 일:

  • run_from_artifacts.py 실행
  • 결과 HTML, measurement, stage snapshot 로드
  • strict 검증 수행
  • 실패 시 retry-plan.json 생성
  • 실패 분류에 따라 rollback stage 결정
  • stage-1b-refined-concepts.json 보정 및 이력 백업 생성
  • 다시 실행 후 재검증
  • validation 결과 기록
  • Step 5 / Step 6 코멘트 파일 작성
  • Gitea 이슈 코멘트 자동 등록

즉, 이 스크립트는 실행 -> 검증 -> retry-plan -> rollback -> 재실행 -> 재검증의 핵심 루프를 담당한다.

retry-plan과 rollback

검증 실패 시 04-plan/retry-plan.json이 생성된다.

이 파일에는 다음이 들어간다.

  • 실패 분류
  • rollback stage
  • 실패 이유
  • 어떤 topic 또는 budget을 어떻게 보정할지에 대한 mutation 목록

또한 04-plan/history/ 아래에 stage 입력의 이전 버전이 백업된다.

예시:

  • stage-1b-refined-concepts.iteration-1.json
  • stage-1b-refined-concepts.iteration-2.json

즉, 루프는 단순히 마지막 HTML을 덮어쓰는 것이 아니라, stage 입력을 보정하고 다시 생성하는 구조다.

strict 검증 기준

현재 합격 기준은 단순히 HTML이 만들어졌는가가 아니다.

아래가 모두 충족되어야 pass다.

  • slide overflow = false
  • body overflow = false
  • sidebar overflow = false
  • footer overflow = false
  • 핵심 메시지 가시 텍스트 존재
  • 이미지/도해 참조 문구 존재
  • 비교 핵심 4축(범위, 프로세스, 성과품, 확장성) 존재
  • 관계도 블록 존재

즉, 측정 통과 + 가시 정보 보존 + 슬라이드 구조 유지가 모두 만족되어야 한다.

주요 스크립트

scripts/run_from_artifacts.py

역할:

  • Step 4에서 만들어진 입력 산출물을 사용해 실제 stage 실행 수행
  • stage snapshot 저장
  • generated_html.json, final.html, measurement.json, context.json, final_context.json 저장
  • retry-plan.json이 있으면 stage_2에서 재생성 전략 적용

scripts/auto_loop_runner.py

역할:

  • 실행 결과를 다시 읽음
  • strict 검증 수행
  • 실패 시 retry-plan 생성
  • rollback 기준에 따라 stage 입력 보정
  • validation 기록 저장
  • Step 5 / Step 6 코멘트 자동 생성
  • Gitea 이슈 코멘트 자동 등록

scripts/gitea_issue_sync.py

역할:

  • Gitea REST API를 통해 이슈 생성, 본문 수정, 코멘트 등록 수행

Gitea 이슈 운영 방식

이슈는 Step 단위로 관리한다.

예시:

  • Step-1-Input-Review
  • Step-2-Interpretation
  • Step-3-Content-Structuring
  • Step-4-Execution-Planning
  • Step-5-Execution
  • Step-6-Validation-and-Recording

실행 결과는 각 step 이슈의 코멘트로 누적된다.

즉:

  • 이슈 본문 = step 정의와 KPI
  • 이슈 코멘트 = 실제 실행 결과

Gitea 자동 코멘트 등록

필요 환경변수:

  • GITEA_URL
  • GITEA_TOKEN

예시:

$env:GITEA_URL="https://gitea.hmac.kr"
$env:GITEA_TOKEN="발급받은_개인_액세스_토큰"

주의:

  • 토큰은 채팅이나 문서에 그대로 남기지 않는다.
  • 노출된 토큰은 즉시 폐기하고 새로 발급한다.

새 run을 시작하는 방법

  1. docs/run-template/를 복사해 새 run 폴더를 만든다.
  2. 원본 mdx를 01-input/에 넣는다.
  3. 필요한 Step 1 ~ Step 4 산출물을 채운다.
  4. 위키의 Prompt를 기준으로 실행한다.
  5. scripts/auto_loop_runner.py를 실행한다.
  6. 결과와 retry-plan, history를 확인한다.

사람이 실제로 하는 최소 판단

이 시스템이 자동화된 뒤에도 사람은 최소한 아래를 확인하는 것이 좋다.

  • 최종 final.html이 실제 사용 목적에 맞는가
  • 너무 과하게 압축되지는 않았는가
  • 표현 톤이나 정보 강조가 의도와 맞는가
  • stage rollback 방향이 설득력 있는가

즉, 시스템의 pass는 운영 기준 합격이고, 최종 실사용 품질은 사람 검토로 한 번 더 확인하면 가장 좋다.

결과물 확인 위치

주요 결과물:

  • 최종 HTML: docs/run-001/05-execution/final.html
  • 생성 HTML JSON: docs/run-001/05-execution/generated_html.json
  • 측정 결과: docs/run-001/05-execution/measurement.json
  • 검증 결과: docs/run-001/06-validation/validation-result.md
  • 재시도 계획: docs/run-001/04-plan/retry-plan.json
  • 재시도 이력: docs/run-001/04-plan/history/

현재 상태

현재 run-001은 strict 기준으로 pass를 달성했다.

즉, 이 저장소는 이제 다음을 실제로 수행할 수 있다.

  • mdx 입력을 저장소 안에 둔다.
  • Codex가 위키와 이슈를 읽는다.
  • 단계별 실행을 수행한다.
  • stage snapshot을 저장한다.
  • strict 검증을 수행한다.
  • 실패 시 retry-plan과 rollback으로 재실행한다.
  • Gitea 이슈 코멘트로 결과를 남긴다.

한 줄 요약

이 저장소는 Codex + Gitea + docs/run-xxx 구조를 이용해 누구라도 mdx -> 슬라이드 변환을 반복 실행하고 검증하고 개선할 수 있도록 만든 운영 저장소다.

Reference in New Issue View Git Blame Copy Permalink
Description
No description provided
Readme 16 MiB
Languages
HTML 70.7%
Python 26.9%
Astro 2.4%