docs: organize project guidance and module contracts
This commit is contained in:
KOKO\Mimi
@@ -0,0 +1,133 @@
|
||||
# FESA 개발 규칙
|
||||
|
||||
## 계약과 변경 범위
|
||||
|
||||
요구조건, 정식화, 부호, 단위, 좌표계, source identity와 수치 기준을 구현 전에 고정한다.
|
||||
구현 편의나 실패한 결과를 이유로 승인된 의미를 조용히 변경하지 않는다. Physics·지원
|
||||
범위·공개 호환성·acceptance·영속 schema 변경과 해결되지 않은 필수 reference 충돌은
|
||||
사용자 결정 사항이다. 이미 승인된 일반 수정과 인계에는 반복 승인 절차를 추가하지 않는다.
|
||||
|
||||
요청 범위에 필요한 최소 변경만 한다. 미래 기능을 위한 state·base class·registry를
|
||||
선할당하지 않는다. 다른 작업자의 변경을 되돌리거나 주변 코드를 함께 정리하지 않는다.
|
||||
계획 요청만으로 solver 구현이나 외부 실행을 시작하지 않는다.
|
||||
|
||||
## 의존성과 소유권
|
||||
|
||||
- Public core는 concrete I/O adapter나 MKL·TBB·HDF5·Win32 타입에 의존하지 않는다.
|
||||
Backend 교체는 interface 경계 뒤에서 처리하고 vendor 오류는 공개 실패 형식으로 변환한다.
|
||||
- Domain은 전체 모델 정의를 소유하고 파싱 이후 가능한 한 불변이다. AnalysisModel은
|
||||
복사본이 아닌 non-owning view이며 Domain이 view보다 오래 살아야 한다.
|
||||
- DofManager가 자유도 정의·free/constrained mapping·equation 번호·sparse pattern을
|
||||
전담한다. Node와 Element에 equation 번호를 저장하지 않는다.
|
||||
- Element/material은 local response, assembly는 global reduction, procedure는 해법과
|
||||
상태 수명, recovery는 물리량, writer는 serialization을 소유한다. 책임을 역전하지 않는다.
|
||||
- Procedure가 실제 사용하는 mutable state만 할당한다. Trial을 검증한 뒤 commit하고
|
||||
실패한 candidate가 기존 state나 최종 HDF5를 부분적으로 오염시키지 않게 한다.
|
||||
|
||||
## 수치 코드
|
||||
|
||||
Element-local contribution을 stable ordering으로 생성하고 고정된 순서로 합산한다.
|
||||
병렬 worker는 자기 index의 buffer만 갱신하며 global CSR이나 결과 row를 공유 누적하지
|
||||
않는다. Hash 순서나 thread scheduling이 sparse structure·결과·진단 순서를 결정하면 안 된다.
|
||||
|
||||
선형 정적 해석은 full K를 stable free/constrained 순서로 분할하고 `Kff` factorization을
|
||||
load assembly보다 먼저 수행한다. 유효한 all-constrained의 빈 free system을 singular로
|
||||
바꾸지 않는다. 반력과 free 평형은 같은 full residual에서 복구한다.
|
||||
|
||||
서로 다른 결과 위치·단위·부호·source identity를 평균으로 합치지 않는다. 식이나
|
||||
reduction 순서를 바꾸는 최적화도 수치 변경이다. 임의 absolute floor, zero clamp,
|
||||
missing-row 무시, 실패 시 다른 물성·질량·solver로의 silent fallback을 추가하지 않는다.
|
||||
|
||||
## C++ 규약
|
||||
|
||||
현재 검증 기준은 C++17 이상, Windows MSVC x64 Debug, CMake target과 CTest다.
|
||||
다른 backend를 지원하는 실행 스크립트가 FESA의 다른 platform 검증을 뜻하지 않는다.
|
||||
새 compiler warning을 추가하지 않는다. Vendor target에 FESA warning 정책을 강제하지 않는다.
|
||||
|
||||
| 대상 | 규칙 |
|
||||
| --- | --- |
|
||||
| 파일·namespace | 소문자 snake_case, source `.cpp`, header `.h` |
|
||||
| 타입·함수·accessor | PascalCase; constructor·destructor·operator는 언어 규칙 |
|
||||
| 변수·parameter | snake_case |
|
||||
| Class 멤버 | snake_case 뒤 `_`; struct record는 trailing `_` 없음 |
|
||||
| 상수·enumerator | `kPascalCase` |
|
||||
| Header | Self-contained include와 repository 경로 기반 include guard; `#pragma once`로 대체하지 않음 |
|
||||
| Formatting | Google 기반 `.clang-format`, space 2개, 통상 80자, namespace 본문 들여쓰기 없음 |
|
||||
|
||||
Include는 대응 header, C, C++ standard, third-party, FESA 순서로 그룹화하고 그룹 내부는
|
||||
알파벳순이다. Transitive include에 의존하지 않는다. 한 statement에 한 declaration을
|
||||
두고 변수를 가능한 좁은 범위에서 초기화한다. 의미 없는 type modifier를 장식으로 붙이지 않는다.
|
||||
|
||||
RAII와 단독 ownership의 `unique_ptr`를 우선한다. 실제 공유 수명이 없는 `shared_ptr`,
|
||||
미래용 virtual method, static 함수 묶음용 class를 만들지 않는다. Polymorphic base는
|
||||
public virtual destructor를 갖고, non-owning 수명은 API 계약에 적는다.
|
||||
|
||||
Expected failure는 `Status` 또는 `Result<T>`다. Backend exception을 그대로 외부로
|
||||
노출하지 않는다. 같은 물리·단위·좌표·실패·소유권 의미일 때만 공통화하며, 코드 모양만
|
||||
비슷한 다른 정식화를 합치지 않는다.
|
||||
|
||||
Production의 public/protected 선언과 private/internal 함수에는 필요한 목적·수명·단위·
|
||||
부호·실패·결정적 순서를 기록한다. Public API Doxygen는 영어를 기본으로 하고 테스트에
|
||||
형식적인 Doxygen를 요구하지 않는다. 코드 동작의 번역보다 비자명한 이유를 설명한다.
|
||||
Formatting-only 변경은 동작 변경과 같은 commit에 섞지 않는다.
|
||||
|
||||
## 검증 조건
|
||||
|
||||
1. 동작·interface 변경은 해당 의미를 확인하는 테스트로 검증한다. 버그는 가능한 경우
|
||||
실패를 먼저 재현하고 최소 수정한다. Coverage가 충분한 rename이나 문서 작업에는
|
||||
구현을 반복하는 형식적 테스트를 추가하지 않는다.
|
||||
2. 수식·요소·재료·적분·상태 갱신 변경에는 독립 numerical review와 해당 analytical/
|
||||
invariant 검사를 수행한다. 필요한 물리·reference 검증도 유지한다.
|
||||
3. 개발 중에는 관련 검사를 실행한다. 솔버 기능 완료 시 구성된 전체 build/test와 필수
|
||||
reference 비교를 한 번 수행한다. 이후 변경·실패·미해결 우려가 없으면 반복하지 않는다.
|
||||
4. 외부 비교는 row identity·component·finite 검사를 먼저 통과해야 한다. 수치 기준이나
|
||||
reference 경로·값을 구현 결과에 맞춰 바꾸지 않는다. 기존 비교 기준 변경은 승인·결정
|
||||
기록·경계값 테스트·영향받는 비교의 재실행을 요구한다.
|
||||
5. 문서만 수정하면 링크·source 대조·diff 정적 검토를 하고 build/test는 실행하지 않는다.
|
||||
미실행·실패·과거 revision의 결과를 현재 통과로 표시하지 않는다.
|
||||
6. Runner, CTest, Python 회귀, 독립 물리 검토의 성공 범위는 각각 다르다. 실행기 exit 0만으로
|
||||
모든 검증이나 외부 배포 준비가 완료됐다고 보고하지 않는다.
|
||||
|
||||
## 작업 배정과 실패 처리
|
||||
|
||||
메인이 필요한 전문 작업만 선택한다. 작은 작업은 직접 수행하며 고정 stage 순회,
|
||||
별도 coordinator, 자동 retry 예산을 도입하지 않는다. 일반 실패는 현재 구현 owner가
|
||||
수정하고 새 근거·변경 없이 같은 명령이나 agent 호출을 반복하지 않는다.
|
||||
|
||||
| 작업 | 담당과 적용 조건 |
|
||||
| --- | --- |
|
||||
| 요구사항 | `requirement-agent`: 복잡하거나 상충하는 범위·acceptance |
|
||||
| 근거 조사 | `research-agent`: 부족한 이론·benchmark·reference 근거 |
|
||||
| 정식화 | `formulation-agent`: 새 수식·요소·해석 알고리즘 |
|
||||
| 독립 수치 검토 | `numerical-review-agent`: 정식화·수치 변경·불일치 |
|
||||
| 입력·결과 | `io-definition-agent`: syntax·진단·schema·비교 mapping |
|
||||
| 구현 | 메인 또는 `implementation-agent`: 위임 이점이 있는 코드 묶음 |
|
||||
| 물리 평가 | `physics-evaluation-agent`: 평형·타당성·coverage |
|
||||
|
||||
일반 역할은 medium, 정식화·수치·물리 역할은 high 추론 강도를 기본으로 한다. 실제 profile과
|
||||
사용 가능한 도구를 확인한다. 인계는 작업·관련 경로/절·수정 파일·검증 기준, 반환은 결과·
|
||||
변경 파일·검사·미해결 항목으로 충분하다. Specialist는 peer에게 재위임하거나 상위 계약을
|
||||
자기 결과에 맞춰 수정하지 않는다. 독립 검토를 자기 승인으로 대체하지 않는다.
|
||||
|
||||
Release-readiness 감사는 별도 명시 요청에만 수행한다. 감사 결과는 release 권한이 아니다.
|
||||
실행기는 내부 LLM·phase 상태기계·자동 Git·대화 종료 hook을 사용하지 않는다.
|
||||
|
||||
## 기능 기록과 Git
|
||||
|
||||
지속할 계약이 필요한 기능에는 stable kebab-case ID와 `docs/<feature-id>/`를 정한다.
|
||||
메인이 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`를 관리한다. 기능 PRD 한 곳에서 현재
|
||||
checklist를 관리하며 복잡한 수식·schema만 별도 전문 문서로 분리한다. `FEATURED_AGENTS.md`는
|
||||
자동 로드되는 코드 영역의 `AGENTS.md`가 아니다.
|
||||
|
||||
기능 문서는 한국어로 작성하고 identifier·field·명령은 원래 표기를 유지한다. 새 요구사항
|
||||
이름은 기존 `FEM-REQ-<FEATURE>-###` 형식을 유지한다. 기존 ID·승인 근거·전문 계약을
|
||||
번호 정리 때문에 변경하지 않는다. 의미 변화 없는 편집마다 hash·인계·gate 기록을 만들지 않는다.
|
||||
|
||||
기존 프로젝트 PRD·ADR·수치 기준과 기능별 계약은 승인된 상세 의미를 보존한다. 공통
|
||||
규칙의 재정리는 그 의미를 변경하지 않는다. 일반 기능 작업은 공통 문서를 읽기 전용으로
|
||||
취급하며 공통 기준 변경은 별도 요청으로 다룬다. 과거 phase·coordination 기록을 재작성하거나
|
||||
현재 실행 입력으로 복원하지 않는다. 전체 진행 현황은 요약이며 기능 checklist를 복제하지 않는다.
|
||||
|
||||
Commit 요청 시 작업 경로만 stage하고 Conventional Commits를 사용한다. Push·tag·publish·
|
||||
파괴적 작업은 명시 범위에 한정한다. 개인 설정·machine 절대 경로·generated build 결과를
|
||||
공용 계약으로 commit하지 않는다.
|
||||
Reference in New Issue
Block a user