본문으로 건너뛰기

제어 평면

.codex 제어 평면은 워크플로 정책과 라우팅을 위한 지속적인 워크스페이스 계층입니다. frontend, backend, worker, infra, docs, 워크스페이스 자동화 작업이 각 저장소 안에 규칙을 중복하지 않고 하나의 실행 모델을 공유하도록 제품 코드와 의도적으로 분리되어 있습니다.

이 문서는 주요 영역과 신뢰 계층에 대한 참고 문서입니다. 정본은 .codex/knowledge/CONTROL_PLANE_RULES.md입니다.

정식 영역​

경로소유 역할용도
.codex/AGENTS.mdTier 1 진입 계약Dispatch Lock, Plan Mode 경계, 기본 loop, 전문 역할 routing, 워크스페이스 참고
.codex/knowledge/**지속 지식hard rule, architecture intent, glossary, 저장소별 규칙 요약
.codex/routing/**라우팅된 SSOT와 참고 문서repo card, loop contract, review matrix, verification selector, branch strategy, doc sync, commit policy
.codex/agents/*.toml전문 역할 정의라우팅된 agent의 역할 설명과 developer instruction
.codex/rules/**경로 범위 저장소 규칙소유 영역별 backend, frontend, worker 집중 규칙
.codex/lint/**checker와 pattern SSOTforbidden-pattern sweep, agent registry check, scope check, commit readiness
.codex/hooks/**hook 구현secret, migration, control-plane scope, Markdown guard, commit check를 위한 좁은 방어선
.codex/hooks.jsonhook 등록어떤 hook script가 어떤 tool class 전후에 실행되는지

repo-local .codex, .codex-plugin, plugin marketplace 파일, dispatcher agent, vendored third-party skill, 워크스페이스 워크플로 하네스를 다시 만들지 않습니다. 제품 저장소는 얇은 local AGENTS.md 추가만 가질 수 있고, workspace router는 중앙에 유지됩니다.

신뢰 계층​

Control-plane 문서는 모두 같은 권한을 갖지 않습니다. 신뢰 계층 모델은 파일이 무엇을 보장할 수 있는지 결정합니다.

Tier이름예시보장하는 것
Tier 0Enforcementhook, lint, test, checker문서를 읽지 않아도 반드시 지켜져야 하는 규칙
Tier 1항상 로드되는 core.codex/AGENTS.md, HARD_RULES_CROSS.md진입 계약, hard stop, 다음 routing 위치
Tier 2Routed SSOTrepo card, loop contract, review matrix, commit policy, doc sync, verification selector상황에 맞게 로드되는 결정
Tier 3Referenceplanning template, implementation runbook, review rubric, sharp-edge catalog중요한 invariant의 유일한 장벽이 될 수 없는 실행 도움말

반복 실패가 누군가 prose를 읽는 것에 의존한다면, 그 prose를 참고 지침으로 낮추거나 invariant를 Tier 0 enforcement로 올립니다.

Dispatch Lock​

Dispatch Lock은 도구 사용, 편집, 하위 에이전트 라우팅, 리뷰, 검증, 커밋 전에 거치는 진입 게이트입니다. 트리거된 저장소와 규칙 영역, 현재 소유 영역, 필요한 모드 또는 게이트, 허용된 다음 행동을 기록합니다.

소유 영역이나 모드가 불명확하다면 다음 행동은 편집이 아닙니다. dispatch를 해결하는 것입니다.

커스텀 에이전트​

커스텀 에이전트는 .codex/agents/*.toml 아래 TOML 파일로 존재합니다. 각 정의는 다음을 제공해야 합니다.

  • name;
  • description;
  • model;
  • developer_instructions.

Agent TOML은 prompt guidance이지 enforcement boundary가 아닙니다. 독립적으로 반드시 지켜져야 하는 도구 권한, 쓰기 범위, 보안 게이트, commit gate는 hook, lint, test, checker 또는 tool filter가 필요합니다.

registry shape를 검증하려면 .codex/lint/agent-registry-checker.sh를 사용합니다. TOML agent 정의를 Markdown frontmatter로 lint하지 마세요.

Hook과 Lint​

Hook은 좁고 맥락이 제한된 방어선입니다. Hook 출력은 작업을 막을 수 있지만 write, Check, Review, commit을 승인하지 않습니다.

Lint는 넓은 금지 패턴 탐지를 소유합니다. regex의 정본은 .codex/lint/patterns/<lang>.yaml이고, 호출자는 bash .codex/lint/sweep.sh를 사용합니다. agent, hook, 라우팅 문서, ad hoc script는 중복 regex copy를 가지면 안 됩니다.

Control-Plane 변경 규율​

.codex policy, guardrail, review routing, commit policy, hook, lint enforcement, shared SSOT 참고 문서를 바꾸려면 planning이나 editing 전에 control-plane 영향 지도가 필요합니다. 지도는 다음을 기록합니다.

  • 정식 파일;
  • 연결된 참고 문서;
  • review와 checker surface;
  • 영향을 받는 work-log 또는 commit-readiness 필드;
  • docs 또는 감사 후속 조치.

각 touched SSOT는 update, deprecate, supersede, explicit defer로 표시해야 합니다. 지도가 여러 control-plane SSOT에 걸치면 구체적인 runtime-risk 트리거가 더 넓은 조정을 요구하지 않는 한 하나의 조정된 control-plane 작업 단위로 유지합니다.

검증​

control-plane 구조는 이 소스 파일로 검증합니다.

sed -n '1,220p' .codex/knowledge/CONTROL_PLANE_RULES.md
sed -n '1,220p' .codex/AGENTS.md
bash .codex/lint/agent-registry-checker.sh

예상 성공 신호: 앞의 두 명령은 현재 surface와 entry gate를 보여주고, registry checker는 agent TOML file에 대해 성공 종료합니다.

관련 문서​