modify framework

2026-06-02 09:51:30 +09:00
parent 88d8613847
commit a292238675
13 changed files with 602 additions and 169 deletions
@@ -1,21 +1,34 @@
 # Architecture Decision Records

 ## 철학
-{프로젝트의 핵심 가치관 (예: MVP 속도 최우선. 외부 의존성 최소화. 작동하는 최소 구현을 선택.)}
+Harness는 현재 프로젝트의 실제 기술 스택을 반영해야 한다. C++/MSVC 프로젝트에서 npm, Next.js, TypeScript test naming을 기본값으로 두면 agent prompt와 hook policy가 잘못된 구현을 유도한다.

 ---

-### ADR-001: {결정 사항 (예: Next.js App Router 선택)}
-**결정**: {뭘 선택했는지}
-**이유**: {왜 선택했는지}
-**트레이드오프**: {뭘 포기했는지}
+### ADR-001: C++ 전용 Harness
+**결정**: Harness scaffold는 C++/MSVC 전용으로 운영한다. JavaScript/TypeScript fallback은 유지하지 않는다.

-### ADR-002: {결정 사항}
-**결정**: {뭘 선택했는지}
-**이유**: {왜 선택했는지}
-**트레이드오프**: {뭘 포기했는지}
+**이유**: FESA 개발 환경은 MSVC 기반 C++이다. 언어별 fallback을 남기면 validation, TDD guard, acceptance criteria가 흐려진다.

-### ADR-003: {결정 사항}
-**결정**: {뭘 선택했는지}
-**이유**: {왜 선택했는지}
-**트레이드오프**: {뭘 포기했는지}
+**트레이드오프**: 같은 Harness scaffold를 JS/TS 프로젝트에 재사용할 수 없다. 필요하면 별도 template이나 language registry를 새 ADR로 설계한다.
+
+### ADR-002: CMake/MSVC/x64/Debug 기본 검증
+**결정**: 기본 workspace validation은 CMake, Visual Studio 17 2022 generator, x64 platform, Debug config, CTest로 수행한다.
+
+**이유**: MSVC 환경에서 CMake/CTest는 source tree가 복원되거나 새 C++ project가 추가될 때 가장 일관된 build/test entry point다.
+
+**트레이드오프**: Visual Studio solution-only project는 기본 지원하지 않는다. 명시적으로 필요하면 `HARNESS_VALIDATION_COMMANDS`로 override한다.
+
+### ADR-003: 엄격한 C++ TDD Guard
+**결정**: C++ production file 변경은 관련 C++ test file이 없으면 차단한다.
+
+**이유**: Harness의 핵심 목적은 agent가 검증 없는 C++ 변경을 만들지 않도록 하는 것이다. Header 중심 C++ 구조에서도 module 또는 basename 기반 테스트 존재를 확인한다.
+
+**트레이드오프**: 초기 scaffolding 작업에서 guard가 엄격하게 느껴질 수 있다. 문서, CMake 설정, Harness metadata는 guard 대상에서 제외한다.
+
+### ADR-004: Harness 자체 테스트 우선
+**결정**: commit hook은 먼저 Python Harness self-test를 실행한 뒤 workspace validation을 실행한다.
+
+**이유**: 현재 저장소에는 C++ source tree가 없을 수 있다. Harness가 스스로 검증 가능해야 이후 phase generation과 source restoration을 안전하게 진행할 수 있다.
+
+**트레이드오프**: commit 시간이 조금 늘어난다. 대신 hook/validation regressions를 빠르게 잡는다.
@@ -1,24 +1,58 @@
 # 아키텍처

-## 디렉토리 구조
-```
-src/
-├── app/               # 페이지 + API 라우트
-├── components/        # UI 컴포넌트
-├── types/             # TypeScript 타입 정의
-├── lib/               # 유틸리티 + 헬퍼
-└── services/          # 외부 API 래퍼
-```
+## 목표
+이 저장소의 현재 책임은 C++/MSVC 프로젝트를 위한 Codex Harness scaffold를 제공하는 것이다. Harness는 phase execution, edit guard, commit validation, workspace validation을 분리해서 관리한다.

-## 패턴
-{사용하는 디자인 패턴 (예: Server Components 기본, 인터랙션이 필요한 곳만 Client Component)}
+## 디렉토리 구조
+```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
+```

 ## 데이터 흐름
-```
-{데이터가 어떻게 흐르는지 (예:
-사용자 입력 → Client Component → API Route → 외부 API → 응답 → UI 업데이트
-)}
+```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
 ```

-## 상태 관리
-{상태 관리 방식 (예: 서버 상태는 Server Components, 클라이언트 상태는 useState/useReducer)}
+## Hook 흐름
+```text
+apply_patch/Edit/Write
+-> .codex/hooks/tdd-guard.py
+-> C++ production changes require related tests
+
+git commit command
+-> .codex/hooks/pre_commit_checks.py
+-> Python Harness self-tests
+-> scripts/validate_workspace.py
+```
+
+## Validation 흐름
+```text
+HARNESS_VALIDATION_COMMANDS set
+-> run exact commands
+
+CMakePresets.json has msvc-debug configure preset
+-> cmake --preset msvc-debug
+-> cmake --build preset binary dir --config Debug
+-> ctest --test-dir preset binary dir -C Debug
+
+CMakeLists.txt exists
+-> cmake -S . -B build/msvc-debug -G "Visual Studio 17 2022" -A x64
+-> cmake --build build/msvc-debug --config Debug
+-> ctest --test-dir build/msvc-debug --output-on-failure -C Debug
+
+No CMake project
+-> print guidance and exit successfully
+```
@@ -1,21 +1,22 @@
-# PRD: {프로젝트명}
+# PRD: C++/MSVC Harness

 ## 목표
-{이 프로젝트가 해결하려는 문제를 한 줄로 요약}
+Codex Harness가 C++/MSVC 프로젝트에서 phase planning, TDD guard, commit validation, workspace validation을 일관되게 수행하게 한다.

 ## 사용자
-{누가 이 제품을 쓰는지}
+- Windows/MSVC 기반 C++ 개발자
+- Harness phase를 작성하고 실행하는 Codex agent
+- Harness 결과를 검토하는 reviewer

 ## 핵심 기능
-1. {기능 1}
-2. {기능 2}
-3. {기능 3}
+1. CMake/MSVC/x64/Debug 기반 workspace validation
+2. C++ source/header 변경에 대한 엄격한 TDD guard
+3. npm 없이 Python self-test와 CMake/CTest 검증을 수행하는 pre-commit hook
+4. C++ 프로젝트에 맞는 Harness workflow/review prompt
+5. CMake project가 아직 없어도 Harness 자체 테스트가 가능한 no-op validation path

-## MVP 제외 사항
- {안 만들 것 1}
- {안 만들 것 2}
- {안 만들 것 3}
-
-## 디자인
- {디자인 방향 (예: 다크모드 고정, 미니멀)}
- {색상 (예: 무채색 + 포인트 1가지)}
+## 제외 사항
+- 이전 FESA solver source tree 복원
+- JavaScript/TypeScript fallback 유지
+- Abaqus reference artifact 생성 또는 solver reference 비교 구현
+- Visual Studio `.sln`/`.vcxproj` 전용 MSBuild workflow