Agentic-AI-Template/Codex/Coding/Codex-cs/docs/ARCHITECTURE.md

아키텍처

목표

이 저장소의 현재 책임은 C#/.NET SDK 프로젝트를 위한 Codex Harness scaffold를 제공하는 것이다. Harness는 phase execution, edit guard, commit validation, workspace validation을 분리해서 관리한다.

Application과 test target은 C#/.NET SDK를 사용하고 Harness script는 Python 3으로 실행한다. Harness는 PATH에 설치된 dotnet을 그대로 사용한다. .NET SDK 버전을 선택하거나 설치하지 않으며 global.json을 생성하거나 고정하지 않는다.

디렉토리 구조

.codex/
├── hooks/              # Codex hook scripts
└── skills/             # Harness planning/review instructions
docs/                   # Project and Harness guidance
scripts/
├── execute.py          # Phase step executor
├── validate_workspace.py
└── test_*.py           # Harness self-tests
phases/                 # Optional generated phase plans

데이터 흐름

User-approved task
-> Harness phase files under phases/
-> scripts/execute.py injects AGENTS.md and docs/*.md
-> Codex executes one step at a time
-> step updates phases/{phase}/index.json
-> validation runs through scripts/validate_workspace.py

Hook 흐름

apply_patch/Edit/Write
-> .codex/hooks/tdd-guard.py
-> C# production .cs changes require related C# test files

git commit command
-> .codex/hooks/pre_commit_checks.py
-> Python Harness self-tests
-> scripts/validate_workspace.py

Validation 흐름

python scripts/validate_workspace.py
-> HARNESS_VALIDATION_COMMANDS set?
   -> yes: run the exact override commands; skip automatic target discovery
   -> no: inspect repository-root targets

Exactly one root .sln exists
-> select that solution, even when root .csproj files also exist

No root .sln exists and exactly one root SDK-style .csproj exists
-> select that project as the single-project fallback

Multiple targets exist at the same active priority
-> report ambiguity and exit with an error; never choose arbitrarily

No root solution or SDK-style project exists
-> print guidance and exit successfully

Selected target
-> dotnet restore <target>
-> dotnet build <target> --configuration Debug --no-restore
-> dotnet test <target> --configuration Debug --no-build --no-restore

다중 project 저장소는 루트 solution에 모든 build/test 대상을 포함해야 한다. 루트의 단일 SDK-style .csproj fallback은 단일-project 저장소만을 위한 경로다.