add framework

2026-09-04 17:00:34 +09:00
parent 0adb9c26a9
commit 1239d5b9f6
18 changed files with 1320 additions and 2 deletions
@@ -0,0 +1,68 @@
+# 아키텍처
+
+## 목표
+이 저장소의 현재 책임은 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`을 생성하거나 고정하지 않는다.
+
+## 디렉토리 구조
+```text
+.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
+```
+
+## 데이터 흐름
+```text
+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 흐름
+```text
+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 흐름
+```text
+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 저장소만을 위한 경로다.