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에 대해 다음 순서로 실행한다.

dotnet restore <target>
dotnet build <target> --configuration Debug --no-restore
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을 빠르게 발견한다.

3.7 KiB Raw Blame History