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,52 @@
+# Architecture Decision Records
+
+## 철학
+Harness는 현재 프로젝트의 실제 기술 스택을 반영해야 한다. 이 저장소는 C#/.NET SDK 전용 정책을 사용하며 다른 언어의 fallback이나 언어별 profile/registry를 두지 않는다.
+
+---
+
+### ADR-001: C#/.NET 전용 Harness
+**결정**: Harness scaffold는 C#/.NET SDK와 `dotnet` CLI 전용으로 운영하고, Harness script에는 Python 3을 사용한다. 언어별 profile이나 registry 및 다른 언어 fallback은 두지 않는다.
+
+**이유**: 단일 기술 스택을 명시해야 validation, TDD guard, acceptance criteria가 실제 FESA 개발 환경과 일치한다.
+
+**트레이드오프**: 다른 언어 프로젝트에는 이 Harness를 그대로 재사용할 수 없다.
+
+### ADR-002: 호스트의 .NET SDK 사용
+**결정**: PATH에 설치된 `dotnet`을 사용한다. Harness는 .NET SDK 버전을 선택·설치하지 않으며 `global.json`을 생성하거나 고정하지 않는다.
+
+**이유**: SDK 수명주기와 설치 정책은 개발 환경이 소유하고, Harness는 저장소 검증만 담당한다.
+
+**트레이드오프**: 실행 결과는 호스트에서 해석되는 SDK에 의존하므로 필요한 SDK 제공은 환경 구성의 책임이다.
+
+### ADR-003: 결정적인 루트 target 선택
+**결정**: 자동 탐색은 루트의 단일 `.sln`을 우선한다. solution이 없을 때만 루트의 단일 SDK-style `.csproj`를 단일-project fallback으로 사용한다. 동일 우선순위 대상이 여러 개면 임의 선택하지 않고 오류로 중단한다. solution/project가 없으면 안내 후 성공 종료한다.
+
+**이유**: solution은 다중 project의 build/test 경계를 명시한다. 모호한 대상을 자동 선택하면 일부 project나 test가 검증에서 누락될 수 있고, 아직 application이 없는 Harness scaffold는 자체 테스트가 가능해야 한다.
+
+**트레이드오프**: 다중 project 저장소는 루트 solution에 모든 build/test 대상을 포함해야 한다. 루트 solution이 없고 `.csproj`가 여러 개인 저장소는 명시적으로 구조를 정리해야 한다.
+
+### ADR-004: 표준 workspace validation 순서
+**결정**: 기본 진입점은 `python scripts/validate_workspace.py`이다. `HARNESS_VALIDATION_COMMANDS`가 설정되어 있으면 자동 target 탐색보다 우선하여 지정된 명령을 실행한다. 그렇지 않으면 선택한 target에 대해 다음 순서로 실행한다.
+
+1. `dotnet restore <target>`
+2. `dotnet build <target> --configuration Debug --no-restore`
+3. `dotnet test <target> --configuration Debug --no-build --no-restore`
+
+**이유**: restore, build, test 단계를 분리하고 후속 단계의 암묵적 restore/build를 차단하면 실패 지점과 검증 범위가 명확해진다.
+
+**트레이드오프**: 특수한 저장소는 `HARNESS_VALIDATION_COMMANDS`로 전체 검증 절차를 명시해야 한다.
+
+### ADR-005: 엄격한 C# TDD Guard
+**결정**: C# production `.cs` file 변경은 관련 C# test file이 없으면 차단한다.
+
+**이유**: Harness의 핵심 목적은 agent가 검증 없는 production 변경을 만들지 않도록 하는 것이다.
+
+**트레이드오프**: 초기 scaffolding 작업에서 guard가 엄격하게 느껴질 수 있다. 문서, project 설정, Harness metadata는 guard 대상에서 제외한다.
+
+### ADR-006: Harness 자체 테스트 우선
+**결정**: commit hook은 먼저 Python Harness self-test를 실행한 뒤 `python scripts/validate_workspace.py`를 실행한다.
+
+**이유**: solution/project가 아직 없더라도 Harness 자체는 검증 가능해야 이후 source 및 project 구성을 안전하게 진행할 수 있다.
+
+**트레이드오프**: commit 시간이 조금 늘어나지만 hook/validation regression을 빠르게 발견한다.
@@ -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 저장소만을 위한 경로다.
@@ -0,0 +1,32 @@
+# PRD: C#/.NET Harness
+
+## 목표
+Codex Harness가 C#/.NET SDK 프로젝트에서 phase planning, TDD guard, commit validation, workspace validation을 일관되게 수행하게 한다.
+
+## 기술 스택
+- C#/.NET SDK
+- `dotnet` CLI
+- Harness scripts in Python 3
+
+## 사용자
+- `dotnet` CLI 기반 C#/.NET 개발자
+- Harness phase를 작성하고 실행하는 Codex agent
+- Harness 결과를 검토하는 reviewer
+
+## 핵심 기능
+1. 기본 진입점은 `python scripts/validate_workspace.py`이며, `HARNESS_VALIDATION_COMMANDS`가 설정되어 있으면 자동 탐색보다 우선한다.
+2. 자동 탐색은 루트의 단일 `.sln`을 우선하고, solution이 없으면 루트의 단일 SDK-style `.csproj`를 선택한다. 동일 우선순위 대상이 여러 개면 임의 선택하지 않고 오류로 중단한다.
+3. 선택한 target에 대해 `dotnet restore <target>`, `dotnet build <target> --configuration Debug --no-restore`, `dotnet test <target> --configuration Debug --no-build --no-restore` 순서로 검증한다.
+4. PATH에 설치된 `dotnet`을 사용하며 Harness는 .NET SDK 버전이나 `global.json`을 생성하거나 고정하지 않는다.
+5. C# production `.cs` 변경에 관련 C# test file을 요구하는 엄격한 TDD guard를 제공한다.
+6. 다중 project 저장소는 루트 solution에 모든 build/test 대상을 포함해야 하며, 단일 `.csproj` fallback은 단일-project 저장소에서만 사용한다.
+7. solution/project가 아직 없으면 안내 후 성공 종료하여 Harness 자체 테스트를 허용한다.
+8. commit hook은 Python Harness self-test를 먼저 실행한 뒤 workspace validation을 실행한다.
+
+## 제외 사항
+- 언어별 profile 또는 registry
+- 다른 언어 validation fallback
+- .NET SDK 버전 선택, 설치 또는 `global.json` 생성
+- C# sample application 또는 project 생성
+- 이전 FESA solver source tree 복원
+- Abaqus reference artifact 생성 또는 solver reference 비교 구현
@@ -0,0 +1,76 @@
+# UI 디자인 가이드
+
+## 디자인 원칙
+1. {원칙 1 — 예: "도구처럼 보여야 한다. 마케팅 페이지가 아니라 매일 쓰는 대시보드."}
+2. {원칙 2}
+3. {원칙 3}
+
+## AI 슬롭 안티패턴 — 하지 마라
+| 금지 사항 | 이유 |
+|-----------|------|
+| backdrop-filter: blur() | glass morphism은 AI 템플릿의 가장 흔한 징후 |
+| gradient-text (배경 그라데이션 텍스트) | AI가 만든 SaaS 랜딩의 1번 특징 |
+| "Powered by AI" 배지 | 기능이 아니라 장식. 사용자에게 가치 없음 |
+| box-shadow 글로우 애니메이션 | 네온 글로우 = AI 슬롭 |
+| 보라/인디고 브랜드 색상 | "AI = 보라색" 클리셰 |
+| 모든 카드에 동일한 rounded-2xl | 균일한 둥근 모서리는 템플릿 느낌 |
+| 배경 gradient orb (blur-3xl 원형) | 모든 AI 랜딩 페이지에 있는 장식 |
+
+## 색상
+### 배경
+| 용도 | 값 |
+|------|------|
+| 페이지 | {예: #0a0a0a} |
+| 카드 | {예: #141414} |
+
+### 텍스트
+| 용도 | 값 |
+|------|------|
+| 주 텍스트 | {예: text-white} |
+| 본문 | {예: text-neutral-300} |
+| 보조 | {예: text-neutral-400} |
+| 비활성 | {예: text-neutral-500} |
+
+### 데이터/시맨틱 색상
+| 용도 | 값 |
+|------|------|
+| {긍정/성공} | {예: #22c55e} |
+| {부정/에러} | {예: #ef4444} |
+| {중립/기본} | {예: #525252} |
+
+## 컴포넌트
+### 카드
+```
+{예: rounded-lg bg-[#141414] border border-neutral-800 p-6}
+```
+
+### 버튼
+```
+Primary: {예: rounded-lg bg-white text-black hover:bg-neutral-200}
+Text:    {예: text-neutral-500 hover:text-neutral-300}
+```
+
+### 입력 필드
+```
+{예: rounded-lg bg-neutral-900 border border-neutral-800 px-4 py-3}
+```
+
+## 레이아웃
+- 전체 너비: {예: max-w-5xl}
+- 정렬: {예: 좌측 정렬 기본. 중앙 정렬 금지}
+- 간격: {예: gap-3~4, 섹션 간 space-y-8}
+
+## 타이포그래피
+| 용도 | 스타일 |
+|------|--------|
+| 페이지 제목 | {예: text-4xl font-semibold text-white} |
+| 카드 제목 | {예: text-sm font-medium text-neutral-400} |
+| 본문 | {예: text-sm text-neutral-300 leading-relaxed} |
+
+## 애니메이션
+- {허용할 애니메이션만 나열. 예: fade-in (0.4s), slide-up (0.5s)}
+- {그 외 모든 애니메이션 금지}
+
+## 아이콘
+- {예: SVG 인라인, strokeWidth 1.5}
+- {예: 아이콘 컨테이너(둥근 배경 박스)로 감싸지 않는다}