# 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이 된다.