FESADev/docs/superpowers/specs/2026-08-10-core-documentation-extension-playbook-design.md

FESA Core Documentation Extension Playbook Design

목적

AGENTS.md, docs/PRD.md, docs/ARCHITECTURE.md, docs/ADR.md를 현재 구현에 맞게 보강한다. 작업 완료 이력이나 일시적인 테스트 개수 대신, 다음 기능을 추가할 AI Agent가 바로 사용할 수 있는 해석 흐름, 소유권, 빌드 설정, 수치 불변식, 확장 경계를 기록한다.

문서별 책임

• AGENTS.md: FESA의 배경과 목적, 전체 프로젝트에서 훼손하면 안 되는 개발 원칙, 문서 탐색 순서와 기능 확장 시의 판단 기준을 제공한다. 상세 구현·빌드 매뉴얼의 대체물이 아니다.
• docs/PRD.md: 사용자가 관찰하는 제품 흐름, 구현된 V0 지원 경계, 신규 기능이 제품 기능으로 인정되기 위한 조건을 정의한다.
• docs/ARCHITECTURE.md: 실제 모듈과 target, 객체 소유권, 8단계 해석 수명주기, CMake dependency/runtime graph, 기능 유형별 확장 지점을 설명한다.
• docs/ADR.md: 정규화된 외부 의존성, 결정론적·failure-atomic 경계, 구속 제거와 full residual, 계층형 검증을 장기 결정으로 남긴다.

기록할 구현 사실

1. 입력은 syntax parse와 semantic mapping을 거쳐 불변 Domain이 되고, AnalysisModel은 이를 복사하지 않는 view이다.
2. Analysis::run()은 initialize, model view, DOF/pattern, stiffness/partition, factorization, load/effective RHS, solve/reconstruct, recovery/write 순서를 고정한다.
3. DofManager가 full/free/constrained numbering과 0-based CSR pattern을 단독 소유하며, Node/Element에는 equation ID를 저장하지 않는다.
4. assembly는 element-local buffer, stable COO order, serial ordered reduction으로 결정론적 CSR을 만든다. global sparse storage를 병렬로 직접 갱신하지 않는다.
5. essential constraints는 full K를 Kff/Kfc/Kcf/Kcc로 분할하고 Ff - Kfc*dc를 푼다. fully constrained 0x0 Kff도 유효하다.
6. reaction/equilibrium evidence는 full residual K*d - F를 사용한다. constrained 성분은 physical reaction이고 free 성분은 equilibrium residual이다.
7. 외부 API는 LinearSolver, ParallelFor, ResultsWriter와 math adapter 뒤에 둔다. public header에 MKL/TBB/HDF5/Win32 type을 노출하지 않는다.
8. HDF5 writer는 같은 directory의 temporary file, checked close/reopen self-check, atomic finalization을 사용한다.
9. element end action, section resultant, generalized result, stress identity와 sign convention을 섞지 않으며 station mismatch를 평균내지 않는다.

빌드 및 검증 설계

• direct build는 Visual Studio generator, x64, Debug를 명시한다. 상세 target graph와 runtime 설명은 docs/ARCHITECTURE.md에 두고, AGENTS.md에는 최소 검증 진입점만 둔다.
• FESA_GTEST_SOURCE_DIR는 필수 local source path이다. MKL_DIR, TBB_DIR, HDF5_DIR는 설치 환경에서 package discovery가 되지 않으면 명시한다.
• production은 Fesa::MKL, Fesa::TBB, Fesa::HDF5 normalized target만 사용한다.
• Windows에서는 CLI와 GoogleTest discovery 전에 MKL/TBB/HDF5 및 transitive oneAPI runtime DLL이 executable 옆에 staging되어야 한다.
• 문서 작업 검증은 project hook/Harness를 실행하지 않고 git diff --check, 링크·경로·명령·target 이름의 정적 대조로 제한한다.

기능 확장 플레이북

• 새 element: 요구조건/정식화/I/O mapping을 먼저 고정하고 kernel, model mapping, DOF pattern, assembly, recovery, output, reference/physics evidence를 함께 확장한다.
• 새 load/constraint: semantic target identity, stable source order, full-space vector/matrix, partition/effective RHS, diagnostics와 output을 함께 검토한다.
• 새 analysis procedure: 기존 V0 lifecycle을 조용히 변경하지 않고 별도 orchestration/state/equation 계약과 gate를 정의한다.
• 새 numerical backend: public interface를 유지하고 adapter 내부에만 vendor API, lifecycle, runtime dependency를 격리한다.
• 새 output/reference quantity: mandatory HDF5 schema, units/coordinates/identity, recovery sign, comparison projection과 tolerance를 동시에 정의한다.

범위 제한

• phase 완료 이력, commit hash, 현재 테스트 총개수 같은 일시적 사실을 핵심 문서에 넣지 않는다.
• full Abaqus compatibility, B31 지원, transform/nested assembly, distributed-load parser exposure 등 승인되지 않은 범위를 암시하지 않는다.
• 문서 보강 외 production, test, CMake, reference artifact를 수정하지 않는다.