김경종
53 lines
3.7 KiB
Markdown
53 lines
3.7 KiB
Markdown
# 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을 빠르게 발견한다.
|