Kyeongmin/C.E.L._slide_test
1
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
184e8165b246f1198ba1638ec963600f954a33f3
C.E.L._slide_test/docs/codex.md

9.4 KiB
Raw Blame History

codex.md

목적

이 문서는 design_agent를 현재 구현 상태에서 바로 뜯어고치는 대신, 먼저 작업 절차와 판단 기준을 design_agnet_codex의 위키/이슈 체계로 외부화한 뒤, 이를 기반으로 Kei API 의존을 제거하는 방향과 실행 계획을 정리한 기준 문서다.

핵심 목표는 다음과 같다.

  • design_agent의 현재 프로세스를 위키와 이슈 체계로 정리한다.
  • Kei API가 담당하던 사고 단계를 문서 기반/에이전트 기반 단계로 치환한다.
  • 후반부의 계산, 생성, 검증, 렌더링은 기존 코드 자산을 최대한 활용한다.
  • 최종적으로 Kei API 없이도 design_agent가 운영 가능하도록 구조를 옮긴다.

현재 인식

현재 design_agent는 다음과 같은 구조를 가진다.

  • 일부 초기 판단 단계에서 Kei API를 호출한다.
  • 이후 단계에서는 공간 계산, HTML 생성, 검증, 렌더링, 측정, 품질 게이트를 코드로 수행한다.
  • 즉, 전체 시스템이 전부 Kei API에 의존하는 것은 아니고, 초반의 해석/구조화 단계가 특히 의존적이다.

문제가 되는 핵심 의존 구간은 다음과 같다.

  • topic extraction
  • concept refinement
  • relation_type 정리
  • expression_hint 정리
  • source_data 보강

이 부분은 현재 Kei API가 맡고 있지만, 앞으로는 위키와 이슈를 기반으로 Codex 또는 Claude Code가 수행하도록 전환해야 한다.

기본 방향

앞으로의 구조는 아래처럼 바뀌어야 한다.

기존 구조:

  • design_agent code -> kei_client.py -> Kei API -> 결과 수신 -> 후속 코드 실행

목표 구조:

  • 위키 1/2/3 -> 이슈에서 현재 작업 정리 -> Codex/Claude가 초기 해석 수행 -> 구조화 산출물 생성 -> design_agent 코드가 후반부 실행

즉, Kei API가 하던 사고 단계는 위키+이슈+에이전트가 맡고, 계산과 생성과 검증은 코드가 맡는 구조로 바꾼다.

역할 분리

위키

위키는 다음을 정의한다.

  • 무엇을 해야 하는가
  • 어떤 순서로 해야 하는가
  • 어떤 기준으로 판단하는가
  • 각 단계의 입력, 출력, 검증 조건은 무엇인가

즉, 위키는 실행 기준서다.

이슈

이슈는 다음을 기록한다.

  • 이번 작업의 실제 입력
  • Kei 기준 해석 결과
  • 구조화 결과
  • 단계별 진행 기록
  • 검증 결과
  • 남은 문제와 다음 액션

즉, 이슈는 실행 기록이자 작업 메모리다.

코드

코드는 다음을 수행한다.

  • 공간 계산
  • 디자인 budget 계산
  • HTML 생성
  • 콘텐츠 검증
  • 렌더링
  • 높이 측정
  • 품질 게이트

즉, 코드는 실행기다.

위키 체계

현재 design_agnet_codex에는 다음 구조를 두는 방향으로 정리한다.

위키 1 계열

Kei의 판단 기준

  • Kei 사고방식과 프로세스
  • Kei 역할과 운영 원칙

위키 2 계열

design_agent 상위 작업 절차

  • 입력 확인
  • Kei 기준 해석
  • 콘텐츠 구조화
  • 실행 계획 수립
  • 실제 수행
  • 검증 및 기록

위키 3 계열

design_agent 상세 파이프라인

  • Stage 0 입력 로드 및 MDX 정규화
  • Stage 1A topic extraction
  • Stage 1B concept refinement
  • Stage 1.5a 폰트 위계와 비율 계획
  • Stage 1.7 참조 블록 선정
  • Stage 1.5b 디자인 버짓 재계산
  • Stage 2 HTML 생성
  • Stage 2 검증 및 재시도
  • Stage 3 렌더와 측정
  • Stage 4 품질 게이트와 최종화

가장 중요한 전환 원칙

위키를 만든다고 자동으로 Kei API가 사라지는 것은 아니다. 진짜 전환은 아래 조건이 충족될 때 일어난다.

  • Stage 1A와 Stage 1B를 Kei API 호출 단계가 아니라 위키/이슈 기반 해석 단계로 재정의한다.
  • Codex 또는 Claude Code가 위키를 읽고 topic/concept/expression_hint/source_data를 직접 정리한다.
  • 이 결과를 코드가 읽을 수 있는 중간 산출물로 남긴다.
  • 이후 후반부 파이프라인은 기존 코드가 그대로 또는 최소 수정으로 수행한다.

즉, 핵심은 Kei API 제거가 아니라 Kei 사고 단계를 외부화하는 것이다.

단계별 실행 계획

1단계. 현재 design_agent 문서화

목적: 현재 design_agent가 어떤 순서로 동작하는지, 어떤 단계가 코드에 있고 어떤 단계가 Kei API에 의존하는지 문서로 고정한다.

할 일:

  • 위키 2와 위키 3을 현재 구조 기준으로 정리한다.
  • 각 stage의 입력/출력/검증 기준을 문서화한다.
  • Phase T 기준 변경점도 함께 반영한다.

2단계. 위키/이슈 기반 작업 체계 완성

목적: Codex/Claude가 Kei persona 프롬프트 대신 위키와 이슈를 읽고 움직이도록 만든다.

할 일:

  • 위키 1 계열 완성
  • 위키 2 계열 완성
  • 위키 3 계열 완성
  • 이슈 템플릿 작성

이 단계가 끝나면 작업 방식은 다음과 같아야 한다.

  • 위키 2를 기준으로 현재 작업 step을 정한다.
  • 판단은 위키 1을 기준으로 한다.
  • 상세 실행은 위키 3을 따른다.
  • 중간 결과와 최종 결과는 이슈에 남긴다.

3단계. Kei API 역할 외부화

목적: 초기 판단 단계가 더 이상 API 호출을 기본 전제로 하지 않게 만든다.

할 일:

  • Stage 1A를 위키 기반 topic extraction으로 재정의한다.
  • Stage 1B를 위키 기반 concept refinement로 재정의한다.
  • relation_type, expression_hint, source_data를 사람이 읽고 검토 가능한 형태로 정리한다.
  • 이를 이슈 또는 별도 산출물 파일에 저장한다.

4단계. 중간 산출물 포맷 정의

목적: 에이전트가 정리한 초기 해석 결과를 코드가 받아 쓸 수 있게 만든다.

예상 산출물 예시:

  • topics.json
  • refined_concepts.json
  • design_context.json
  • 또는 단계별 markdown 기록

이 단계에서 중요한 것은 파일 형식보다도 아래 항목이 안정적으로 남는 것이다.

  • 핵심 topic
  • refined concept
  • relation 정보
  • expression hint
  • source data
  • 검증 기준

5단계. 코드 경로 전환

목적: design_agent가 기본적으로 Kei API를 호출하지 않도록 흐름을 바꾼다.

할 일:

  • kei_client 호출을 기본 경로에서 제거하거나 optional fallback으로 내린다.
  • Stage 1A/1B 입력을 API 응답이 아니라 중간 산출물로 바꾼다.
  • 후반부 파이프라인은 최대한 기존 코드 자산을 유지한다.

원칙:

  • 계산, 생성, 검증 로직은 함부로 다시 쓰지 않는다.
  • 먼저 입력 경로만 바꾼다.
  • 코드 변경은 작고 명확하게 진행한다.

6단계. 운영 방식 정착

목적: 실제 작업이 위키 -> 이슈 -> 코드 실행 흐름으로 안정적으로 반복되게 만든다.

운영 흐름:

  1. 작업 이슈 생성
  2. 위키 2의 현재 step 확인
  3. 위키 1 기준으로 해석
  4. 위키 3 기준으로 상세 실행 계획 수립
  5. 초기 해석 결과 작성
  6. 코드 실행
  7. 검증 결과 기록
  8. 필요한 단계만 재시도

Phase T 반영 원칙

현재는 Phase T 진행 중이므로, 위키 2와 위키 3은 단순히 기존 구현 복제가 아니라 Phase T 목표 구조를 반영해야 한다.

특히 반드시 반영해야 할 항목은 다음과 같다.

  • Stage 0 MDX normalization
  • Stage 1A / 1B 분리
  • Stage 1.5a / 1.7 / 1.5b 분리
  • font hierarchy first
  • PipelineContext 기반 사고
  • 단계별 validation
  • partial retry
  • quality gate

즉, 위키는 현재 코드 설명서이면서 동시에 Phase T 전환 가이드여야 한다.

코드와 문서의 관계

문서는 코드를 대체하지 않는다. 문서는 코드가 어떤 역할을 해야 하는지 지시한다.

예시:

  • 위키: MDX 정규화의 목적, 입력, 출력, 검증 기준 정의

  • 코드: 실제 정규화 수행

  • 위키: topic extraction에서 무엇을 뽑아야 하는지 정의

  • 에이전트 또는 코드: 실제 추출 수행

  • 위키: HTML 생성의 원칙과 실패 기준 정의

  • 코드: 실제 HTML 생성 수행

즉:

  • 위키는 기준
  • 이슈는 기록
  • 코드는 실행

당장 해야 할 일

우선순위는 다음과 같다.

  1. design_agnet_codex의 위키 문서명을 Gitea 형식에 맞게 정리한다.
  2. 위키 3의 Stage 1A/1B 내용을 Kei API 호출형이 아니라 위키/이슈 기반 해석형으로 수정한다.
  3. 이슈 템플릿 문서를 만든다.
  4. Kei API가 하던 초기 판단 산출물 포맷을 정의한다.
  5. 그 다음에야 실제 코드 경로를 전환한다.

기준 문장

앞으로 Codex 또는 Claude Code에게는 아래와 같은 운영 문장을 사용한다.

현재 작업은 위키 2의 상위 작업 절차를 기준으로 진행한다. 판단 기준이 필요하면 위키 1 계열을 참조한다. 상세 실행과 검증은 위키 3 계열을 따른다. 초기 해석 결과와 중간 결과와 최종 결과는 이슈에 기록한다. 가능하면 Kei API를 호출하지 않고 위키와 이슈를 기반으로 Stage 1A와 Stage 1B를 수행한다.

결론

이번 작업의 핵심은 단순히 Kei API를 끄는 것이 아니다. 진짜 목표는 Kei의 사고 단계를 API 안에 가두지 않고, 위키와 이슈와 에이전트 실행 흐름으로 꺼내는 것이다.

이 전환이 완료되면 design_agent는 다음과 같은 구조를 갖게 된다.

  • 사고 기준은 위키에 있고
  • 작업 기억은 이슈에 있고
  • 계산과 생성은 코드가 수행하며
  • Kei API는 필수가 아니라 선택적 fallback이 된다.
Reference in New Issue View Git Blame Copy Permalink