PRD: FESA 구조해석 솔버

제품 정의

FESA는 유한요소법 기반 구조해석 솔버를 단계적으로 구축하는 프로젝트이다. 물리적으로 설명 가능하고 재현 가능한 해석 결과를 제공하며, 새로운 기능을 요구사항부터 독립 검증까지 추적 가능한 단위로 확장하는 것을 목표로 한다.

이 문서는 특정 요소, 재료, 하중 또는 해석 절차의 명세가 아니라 모든 Feature에 적용되는 제품 기준이다. 개별 지원 범위, 입력 옵션, 수식, 수치 기준과 검증 사례는 docs/<feature-id>/의 승인 계약으로 정의한다. 특정 기능의 코드가 존재한다는 사실과 그 기능의 검증 완료 또는 현재 release readiness는 서로 다른 상태다.

현재 선택된 기술 스택과 외부 형식은 프로젝트 지침 및 승인된 계약을 따른다. 공통 문서의 일반화는 기존 지원 범위, 파일 형식, 수치 정책 또는 호환성을 변경하는 승인이 아니다.

대상 사용자

Solver 개발자: 요소, 재료, 하중, 제약, 해석 절차와 수치 backend를 구현한다.
해석 사용자: 문서화된 입력 범위로 모델을 구성하고 결과와 진단을 해석한다.
검증 담당자: 수학적 일관성, 물리적 타당성, reference 비교와 회귀 evidence를 검토한다.
Maintainer와 workflow 운영자: 요구사항, 결정, 구현과 검증의 추적성 및 변경 범위를 관리한다.

제품 목표

해석의 물리·수치 의미를 입력부터 결과까지 보존한다.
작은 Feature를 end-to-end로 완성한 뒤 검증된 기반 위에서 지원 범위를 확장한다.
모델 의미, 계산 상태, 수치 backend와 저장 형식의 책임을 구분한다.
같은 입력과 승인된 실행 조건에서 source identity, 조립·결과·진단 순서를 재현한다.
잘못되거나 지원하지 않는 모델 의미를 조용히 근사하지 않고 명확히 진단한다.
요구사항, 설계 결정, 구현, 테스트와 검증 결과를 같은 Feature와 contract revision으로 연결한다.

Harness와 agent·skill은 이 목표를 달성하기 위한 개발 운영 인프라다. 운영 스크립트나 문서 체계 자체를 구조해석 솔버의 제품 기능으로 간주하지 않는다.

문서와 계약의 역할

문서	소유하는 내용
이 PRD	제품 목적, 공통 요구사항, 품질 속성과 완료 기준
ARCHITECTURE	공통 책임, 의존성, 수명과 확장 경계
ADR	프로젝트 전반의 설계 결정과 변경 이력
Feature `PRD.md`	해당 요구의 목적·범위·제외·acceptance 요약과 상세 요구사항 링크
Feature `requirements.md`	Requirement Agent가 소유하는 검증 가능한 요구사항과 verification matrix
Feature `ADR.md`	해당 Feature의 결정·이유·영향·owner와 승인 근거
Feature 전문 산출물	연구, 정식화, 수치/reference 검토, I/O, 구현·검증, 물리 검토와 release evidence

Feature 문서의 생성·재개, Coordinator 관리 문서와 상세 문서 분리는 FEATURE_DOCUMENTATION을 따른다. Feature PRD가 requirements.md와 별도의 요구사항 원본을 만들거나 공통 기준을 묵시적으로 덮어쓰지 않는다. 공통 기준 자체의 변경은 별도로 승인된 프로젝트 문서 작업으로 다룬다.

공통 기능 요구사항

아래 FESA-PRD-GEN-*는 공통 원칙을 위한 추적 ID다. 기존 FESA-PRD-001부터 FESA-PRD-019까지의 의미를 바꾸어 재사용하지 않으며, 그 원문과 적용 범위는 개정 전 PRD에 보존한다. Feature의 상세 요구사항은 별도 FEM-REQ-<FEATURE>-### ID와 해당 공통 기준을 연결한다.

ID	요구사항	확인할 evidence
FESA-PRD-GEN-001	지원·미지원 범위와 관찰 가능한 동작을 Feature 계약으로 명시해야 한다.	범위·제외·입력/출력 계약 및 양성·음성 검증
FESA-PRD-GEN-002	입력을 일관된 semantic model로 변환하고 잘못된 참조·중복·비유한 값·미지원 조합을 진단해야 한다.	Mapping·validation 계약과 실패 경로 테스트
FESA-PRD-GEN-003	Source identity, internal index, DOF, equation과 result identity를 구분하고 필요한 대응 관계를 보존해야 한다.	Identity mapping과 재정렬·누락·중복 검사
FESA-PRD-GEN-004	모델 정의, 실행 view, equation 구성과 mutable state의 소유권·수명을 분리해야 한다.	Architecture·lifetime 검토와 관련 테스트
FESA-PRD-GEN-005	요소·재료·하중·제약의 수학적 계약을 검토한 뒤 local 계산과 전역 해석을 연결해야 한다.	정식화, Numerical Review, local·integration evidence
FESA-PRD-GEN-006	해석 절차마다 필요한 state, 해법, 종료 조건, commit과 recovery 의미를 정의해야 한다.	Procedure 계약과 성공·실패 lifecycle 검증
FESA-PRD-GEN-007	결과의 물리량, location, units, coordinates, component, entity와 step/frame 의미를 식별할 수 있어야 한다.	I/O·result schema 계약과 mapping 검증
FESA-PRD-GEN-008	실패한 candidate가 유효한 state나 최종 결과를 부분적으로 오염시키지 않도록 계약된 보존 범위를 지켜야 한다.	State commit·복구·출력 실패 검증
FESA-PRD-GEN-009	외부 형식과 vendor/OS API를 adapter 뒤에 격리하고 solver core에 노출하지 않아야 한다.	Public dependency와 adapter 경계 검토
FESA-PRD-GEN-010	Production 동작 변경은 관련 테스트의 기대 실패를 관찰한 뒤 구현하고 지정된 검증 evidence를 남겨야 한다.	RED/GREEN, focused/full 검증 명령과 실제 결과
FESA-PRD-GEN-011	기능에 필요한 독립 검증과 reference 비교를 수행하고 승인된 identity·수치 정책을 유지해야 한다.	검증 matrix, 사전검사, reference 또는 명시적 N/A와 대체 근거
FESA-PRD-GEN-012	기능 완료는 같은 계약 revision의 필수 evidence와 미해결 항목을 추적하여 판정해야 한다.	요구사항부터 물리 검토·release readiness까지의 gate 기록

요구사항 단계는 acceptance intent와 필요한 물리적 관찰을 정한다. Numerical Review는 기존 승인 정책 안에서 논리적 비교량·identity/component·판정 구분을 구체화하고, I/O는 이를 외부 syntax와 결과 schema에 대응시킨다. 구현 담당자가 누락된 상위 계약을 임의로 정하지 않는다.

품질 속성

속성	공통 기준
Correctness	실행 성공이나 유한한 결과만으로 판단하지 않고 수학적 계약과 기능별 검증으로 설명한다.
Determinism	승인된 실행 조건에서 identity, numbering, reduction, 결과와 diagnostic 순서를 재현한다.
Traceability	요구사항·결정·코드·테스트·artifact·verdict를 Feature ID와 revision으로 연결한다.
Extensibility	실제 사용 사례에 필요한 최소 경계를 추가하며, 지원하지 않는 physics나 미래 state를 선할당하지 않는다.
Diagnosability	실패 단계와 관련 source/entity, 원인과 재개에 필요한 정보를 제공한다.
Safety	미지원 의미는 fail-closed로 처리하고, reference와 관련 없는 사용자 변경을 보존한다.
Maintainability	사람이 계약과 수식을 대조할 수 있는 단순한 코드와 중복 없는 문서를 유지한다.
Performance	정확성·재현성을 보존하고 측정된 병목과 승인된 요구를 근거로 최적화한다.

특정 모델 크기, 성능 목표와 환경별 보장은 해당 요구와 evidence가 있을 때 Feature 계약으로 정한다. 수치 검증 기준은 적용되는 공통 정책과 승인된 Feature 계약을 따르며 외부 reference 기준을 기능마다 임의로 정하지 않는다. 이 표는 검증되지 않은 성능이나 모든 platform의 동등성을 약속하지 않는다.

검증과 완료 기준

검증은 서로 다른 오류를 확인하는 계층으로 구성한다. Numerical Review가 Feature에 맞는 unit, analytical/benchmark, integration, convergence, invariant 및 외부 reference coverage를 정의한다. 한 계층의 성공이 다른 필수 계층을 대신하지 않는다.

외부 reference 비교는 identity와 component를 대응시키고 missing, extra, duplicate, nonfinite 값을 거부한 뒤 TOLERANCE를 적용한다.
물리 평형, 수렴과 정식화 검증의 기준을 외부 reference tolerance와 혼용하지 않는다.
Reference artifact는 read-only로 취급하며 구현 결과에 맞추어 생성·보정하지 않는다.
비교가 N/A인 경우 이유와 계약이 요구하는 대체 evidence를 명시한다.
실패·미실행·stale evidence를 통과로 표시하지 않는다. 과거 통과 기록을 현재 검증으로 소급 적용하지 않는다.

정규 Feature workflow는 다음과 같다.

requirements → research → formulation → numerical-review → io-definition → implementation-planning → implementation → physics-evaluation → release-readiness

구현 gate는 TDD, 지정된 전체 build/test와 필수 reference evidence가 갖추어졌을 때 통과한다. Feature closure에는 그 뒤의 독립 물리 검토와 release-readiness 감사도 필요하다. Release readiness는 내부 완료 권고이며 외부 publish, push, tag, deploy 또는 package 권한이 아니다.

Owner, 공통 handoff, outcome, stale 처리와 유한 correction은 SOLVER_AGENT_DESIGN을 따른다. Skill의 적용 경계는 SOLVER_SKILL_DESIGN, 실행 절차는 각 현재 SKILL.md를 따른다. 문서만 수정하는 작업을 solver Feature 전체 workflow로 확대하지 않는다.

단계적 확장과 비목표

새 Feature는 입력 의미부터 결과와 검증까지 연결되는 작은 단위로 정의한다. Kernel, parser 또는 dataset 하나가 존재한다는 이유만으로 제품 노출을 선언하지 않는다. 공통 문서에 구현 항목별 목록이나 진행 상태를 누적하지 않고 해당 Feature 문서에서 관리한다.

다음은 별도 승인 없이 목표로 삼지 않는다.

특정 외부 solver의 전체 호환성이나 비공개 알고리즘·내부 상태·결과 생성 절차의 동등성
아직 요구되거나 검증되지 않은 요소·재료·해석 절차·입출력 형식의 지원
GUI, 모델러, mesher 또는 범용 전후처리기로의 제품 범위 확대
외부 solver 실행, reference 갱신, 원격 게시 또는 파괴적 작업의 자동 승인

외부 제품의 공개 입력 의미, 출력 정의와 검증 사례는 승인된 범위의 reference로 사용할 수 있다. 수치 결과의 exact equality는 허용되지만 내부 동작 동등성을 증명하지 않는다.

개정 이력의 보존

이 개정은 프로젝트 공통 기준과 구현 항목별 계약의 문서 경계를 정리한다. 기존 기능의 요구사항을 폐기하거나 수치 acceptance를 변경하지 않는다. 기능별 설명과 기존 ID의 원문은 개정 전 PRD에 보존하며, 향후 Feature PRD로 이관할 때 원래 범위·revision·근거를 함께 연결한다. 보존본의 오래된 지원·검증 상태보다 해당 Feature의 승인된 최신 계약과 evidence를 확인한다.

12 KiB Raw Blame History