AbaqusSubroutineDev/AGENTS.md

Project: Abaqus User Subroutine Development

프로젝트 정체성

• 이 저장소의 목적은 Abaqus User Subroutine을 요구조건 분석부터 검증까지 일관되게 개발하는 것이다.
• User Subroutine production code는 Fortran을 기본 언어로 작성한다.
• Intel oneAPI Fortran compiler를 기본 컴파일러 체계로 사용한다. 자동 탐지는 ifx를 우선하고, 없으면 ifort를 사용한다.
• 이 프로젝트는 Abaqus job 해석을 직접 실행하지 않는다. 해석은 사용자가 다른 Abaqus PC에서 수행하고, 이 저장소는 ODB에서 추출된 CSV와 provenance artifact를 검증 입력으로 사용한다.
• .codex/agents/와 .codex/skills/는 Abaqus User Subroutine 개발 단계별 전문 agent와 작업 규칙의 기준이다.

기술 스택

• Abaqus User Subroutine in Fortran
• Intel oneAPI Fortran compiler on Windows
• Python 3 validation and automation scripts
• Codex custom agents and skills
• Optional CMake + CTest validation path when a CMake project exists
• Optional MSVC/x64/Debug validation path for supporting native components only

개발 워크플로우

1. Subroutine 요구조건 분석
2. 책, 논문, Abaqus manual, benchmark 등 연구자료 조사
3. 코드 구현을 위한 유한요소 정식화
4. Subroutine 입출력 파라미터와 Abaqus ABI 계약 정의
5. TDD 방법을 사용하는 no-Abaqus test model 및 외부 생성 reference artifact 계약 작성
6. Fortran 코드 구현
7. ODB에서 추출된 CSV 기반 Subroutine 검증, 물리 타당성 검토, readiness audit

Agent / Skill 운영 규칙

• 장기 작업은 위 7단계 gate로 나누고, 각 gate는 독립적으로 검토 가능한 문서 산출물을 남긴다.
• Agent mapping과 gate 정의는 docs/ABAQUS_SUBROUTINE_AGENT_DESIGN.md를 기준으로 한다.
• Requirement Agent는 docs/requirements/<feature-id>.md에 요구조건과 Requirement Verification Matrix를 작성한다.
• Research Agent는 docs/research/<feature-id>-research.md에 source-backed fact, inference, applicability limit를 분리해 기록한다.
• Formulation Agent와 Numerical Review Agent는 formulation, tangent, state variable, numerical risk를 구현 전 검토한다.
• I/O Definition Agent는 Abaqus ABI argument, update responsibility, tensor order, unit, ODB 추출 CSV schema를 명시한다.
• Reference Model Agent는 tests/fortran/manifest.json 계획과 references/<feature-id>/<model-id>/ artifact 계약을 정의한다. 최소 artifact는 model.inp, extracted CSV, .msg/.dat/.log/.sta tail files를 포함해야 한다.
• Implementation Agent는 승인된 implementation plan만 구현하며 RED -> GREEN -> VERIFY 순서를 지킨다.
• Validation, Physics Evaluation, Release Agent는 source code, tests, reference artifacts, tolerances를 임의로 변경하지 않는다.

작업 상태 공유 파일

• 모든 agent는 새 작업을 시작할 때 AGENTS.md를 읽은 뒤 루트의 PLAN.md, PROGRESS.md, WORKNOTE.md를 확인해 현재 목표, 진행 상태, 알려진 시행착오를 파악한다.
• PLAN.md는 현재 목표, phase/step 분해, 성공 기준, 범위 제외, 미해결 결정을 관리한다. 계획이 바뀌면 구현 전에 먼저 갱신한다.
• PROGRESS.md는 완료된 일, 진행 중인 일, 막힌 일, 다음 agent가 바로 수행해야 할 next action, 마지막 검증 명령 결과를 관리한다. step 시작/완료/blocked/error 전환 시 갱신한다.
• WORKNOTE.md는 실수, 실패한 명령, 잘못된 가정, 우회 방법, 재발 방지 메모를 기록한다. 단순 진행 로그를 중복하지 말고 다음 agent에게 도움이 되는 시행착오만 남긴다.
• 여러 agent가 나눠 작업할 때는 PROGRESS.md의 현재 owner/active step을 먼저 확인하고, 자신이 맡은 범위와 변경 파일을 기록한 뒤 작업한다.
• phase 파일(phases/<phase>/stepN.md)과 세 공유 파일이 충돌하면 더 구체적인 phase step 지시를 우선하되, 충돌 사실과 처리 결정을 WORKNOTE.md에 기록한다.
• 작업을 마치기 전에는 PROGRESS.md에 실제 수행한 검증 명령과 결과를 남기고, 새 시행착오가 있으면 WORKNOTE.md를 갱신한다.

아키텍처 규칙

• CRITICAL: 기본 검증 경로는 python scripts/validate_workspace.py이다.
• CRITICAL: 이 프로젝트의 수치 검증은 Abaqus job 실행이 아니라 외부 생성 extracted result validation이다. ODB는 직접 파싱하지 않고, 사용자가 ODB에서 추출한 CSV를 schema/tolerance로 비교한다.
• CRITICAL: 새 기능 또는 동작 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현한다.
• CRITICAL: Fortran user subroutine production file을 바꿀 때는 관련 no-Abaqus Fortran/Python driver test가 있어야 한다.
• CRITICAL: Abaqus reference artifact 등록, 갱신, 승인된 extracted result 복원은 명시적으로 요청된 phase에서만 수행한다.
• Abaqus ABI wrapper는 얇게 유지하고, 테스트 가능한 계산 로직은 no-Abaqus kernel 또는 driver에서 검증 가능하게 분리한다.
• Reference artifacts는 승인 후 read-only evidence로 취급한다.
• Codex custom agent의 model_reasoning_effort 기본값은 extra high로 둔다.
• Codex hook 정책은 .codex/hooks/에 둔다.
• Abaqus User Subroutine planning/review instructions는 .codex/skills/에 둔다.
• Generated phase execution outputs remain ignored under phases/**/step*-output.json.

검증 명령어

python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py
python scripts/validate_fortran.py
python scripts/validate_reference_artifacts.py
python scripts/execute.py <phase-dir>
python scripts/execute.py <phase-dir> --push

Fortran / External Result 검증 기본값

• HARNESS_FORTRAN_VALIDATION=auto: tests/fortran/manifest.json이 있으면 Intel Fortran no-Abaqus tests를 실행한다.
• HARNESS_FORTRAN_VALIDATION=off: Fortran validation을 건너뛴다.
• HARNESS_FORTRAN_VALIDATION=detect: manifest와 compiler 감지만 수행하고 compile/run command를 만들지 않는다.
• HARNESS_FORTRAN_COMPILER=auto: ifx를 우선 사용하고, 없으면 ifort를 사용한다.
• HARNESS_ONEAPI_VARS_BAT: Intel oneAPI 환경 설정 batch file override.
• Abaqus job 실행 관련 환경 변수는 legacy/diagnostic capability로만 취급한다. 새 validation workflow는 저장소 내부 Abaqus 해석 실행을 요구하거나 권장하지 않는다.
• Reference validation의 기본 입력은 외부 Abaqus 해석 후 ODB에서 추출된 CSV와 provenance metadata이다.

Supporting CMake / MSVC 검증 기본값

• CMake project가 존재할 때만 CMake/CTest 경로를 실행한다.
• Generator: Visual Studio 17 2022
• Platform: x64
• Config: Debug
• Build directory: build/msvc-debug
• Override variables:
  • HARNESS_VALIDATION_COMMANDS
  • HARNESS_CMAKE_GENERATOR
  • HARNESS_CMAKE_PLATFORM
  • HARNESS_CMAKE_CONFIG
  • HARNESS_BUILD_DIR

개발 프로세스 규칙

• 문서 변경은 관련 구현을 대신하지 않는다. Requirements, research, formulation, interface, test model, implementation, validation evidence를 구분한다.
• 모든 must requirement는 verification method, acceptance criteria, tolerance 또는 decision owner를 가져야 한다.
• Public example repository는 layout과 학습 자료로만 사용한다. Acceptance evidence로 쓰려면 source, license, version, generated artifact provenance를 별도로 기록한다.
• Abaqus model.inp, extracted CSV, .msg/.dat/.log/.sta tail files는 reference artifact contract에 맞춰 저장한다. ODB 자체는 직접 파싱 대상이 아니며, 필요하면 opaque artifact 또는 hash/provenance로만 기록한다.
• 커밋 전 hook은 Python self-test와 workspace validation을 실행해야 한다.
• 커밋 메시지는 conventional commits 형식을 따른다: feat:, fix:, docs:, refactor:, test:.
• 작업이 완료되고 필수 검증이 통과하면 변경 사항을 conventional commit으로 커밋한 뒤 원격 저장소에 push한다.