Consolidate run-001 inputs and docs into repository
This commit is contained in:
216
docs/codex.md
216
docs/codex.md
@@ -1,23 +1,23 @@
|
||||
# codex.md
|
||||
|
||||
## 목적
|
||||
이 문서는 `design_agent`를 현재 구현 상태에서 바로 뜯어고치는 대신, 먼저 작업 절차와 판단 기준을 `design_agnet_codex`의 위키/이슈 체계로 외부화한 뒤, 이를 기반으로 `Kei API` 의존을 제거하는 방향과 실행 계획을 정리한 기준 문서다.
|
||||
이 문서는 `C.E.L._slide_test` 저장소 하나만으로 입력, 절차, 실행, 결과를 닫힌 구조로 운영하기 위한 방향과 실행 계획을 정리한 기준 문서다.
|
||||
|
||||
핵심 목표는 다음과 같다.
|
||||
|
||||
- `design_agent`의 현재 프로세스를 위키와 이슈 체계로 정리한다.
|
||||
- `Kei API`가 담당하던 사고 단계를 문서 기반/에이전트 기반 단계로 치환한다.
|
||||
- 후반부의 계산, 생성, 검증, 렌더링은 기존 코드 자산을 최대한 활용한다.
|
||||
- 최종적으로 `Kei API` 없이도 `design_agent`가 운영 가능하도록 구조를 옮긴다.
|
||||
- 초기 해석 단계는 이슈와 문서 기반으로 수행하고, 후반부 계산과 생성과 검증은 기존 코드 자산을 활용한다.
|
||||
- run마다 입력 원문, 중간 산출물, 실행 결과, 검증 결과를 모두 저장소 안에 남긴다.
|
||||
- 최종적으로 `C.E.L._slide_test` 저장소 하나만 보면 전체 루프를 이해하고 재실행할 수 있게 만든다.
|
||||
|
||||
## 현재 인식
|
||||
현재 `design_agent`는 다음과 같은 구조를 가진다.
|
||||
|
||||
- 일부 초기 판단 단계에서 `Kei API`를 호출한다.
|
||||
- 일부 초기 판단 단계에서 외부 해석 로직에 의존한다.
|
||||
- 이후 단계에서는 공간 계산, HTML 생성, 검증, 렌더링, 측정, 품질 게이트를 코드로 수행한다.
|
||||
- 즉, 전체 시스템이 전부 `Kei API`에 의존하는 것은 아니고, 초반의 해석/구조화 단계가 특히 의존적이다.
|
||||
- 즉, 전체 시스템이 하나의 외부 서비스에만 의존하는 것은 아니고, 초반의 해석/구조화 단계가 특히 분리 필요하다.
|
||||
|
||||
문제가 되는 핵심 의존 구간은 다음과 같다.
|
||||
문제가 되는 핵심 초기 단계는 다음과 같다.
|
||||
|
||||
- topic extraction
|
||||
- concept refinement
|
||||
@@ -25,18 +25,18 @@
|
||||
- expression_hint 정리
|
||||
- source_data 보강
|
||||
|
||||
이 부분은 현재 `Kei API`가 맡고 있지만, 앞으로는 위키와 이슈를 기반으로 Codex 또는 Claude Code가 수행하도록 전환해야 한다.
|
||||
이 부분은 앞으로 위키와 이슈를 기반으로 Codex 또는 Claude Code가 수행하고, 그 결과를 run 산출물로 저장해야 한다.
|
||||
|
||||
## 기본 방향
|
||||
앞으로의 구조는 아래처럼 바뀌어야 한다.
|
||||
앞으로의 구조는 아래처럼 정리한다.
|
||||
|
||||
기존 구조:
|
||||
- `design_agent code -> kei_client.py -> Kei API -> 결과 수신 -> 후속 코드 실행`
|
||||
- `design_agent code -> 외부 해석 -> 결과 수신 -> 후속 코드 실행`
|
||||
|
||||
목표 구조:
|
||||
- `위키 1/2/3 -> 이슈에서 현재 작업 정리 -> Codex/Claude가 초기 해석 수행 -> 구조화 산출물 생성 -> design_agent 코드가 후반부 실행`
|
||||
|
||||
즉, `Kei API`가 하던 사고 단계는 위키+이슈+에이전트가 맡고, 계산과 생성과 검증은 코드가 맡는 구조로 바꾼다.
|
||||
즉, 초기 사고 단계는 위키+이슈+에이전트가 맡고, 계산과 생성과 검증은 코드가 맡는 구조로 바꾼다.
|
||||
|
||||
## 역할 분리
|
||||
### 위키
|
||||
@@ -53,7 +53,7 @@
|
||||
이슈는 다음을 기록한다.
|
||||
|
||||
- 이번 작업의 실제 입력
|
||||
- Kei 기준 해석 결과
|
||||
- 해석 결과
|
||||
- 구조화 결과
|
||||
- 단계별 진행 기록
|
||||
- 검증 결과
|
||||
@@ -74,188 +74,14 @@
|
||||
|
||||
즉, 코드는 실행기다.
|
||||
|
||||
## 위키 체계
|
||||
현재 `design_agnet_codex`에는 다음 구조를 두는 방향으로 정리한다.
|
||||
## 저장소 운영 원칙
|
||||
현재 `C.E.L._slide_test`에는 다음 구조를 유지한다.
|
||||
|
||||
### 위키 1 계열
|
||||
Kei의 판단 기준
|
||||
- `docs/run-xxx/01-input/`: 입력 원문과 입력 검토 결과
|
||||
- `docs/run-xxx/02-kei-interpretation/`: 초기 해석 결과
|
||||
- `docs/run-xxx/03-structure/`: 구조화 결과
|
||||
- `docs/run-xxx/04-plan/`: 실행 계획과 수동 보강 산출물
|
||||
- `docs/run-xxx/05-execution/`: 실제 실행 결과
|
||||
- `docs/run-xxx/06-validation/`: 검증 결과
|
||||
|
||||
- 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
Block a user