baram2584/AbaqusSubroutineDev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3cd5a21892ebe6d8f23d620375a40348a7be7f9f
AbaqusSubroutineDev/AGENTS.md
T
KOKO\Mimi e76c1b96fd docs: refresh Abaqus subroutine guidance
2026-08-18 11:27:22 +09:00

9.3 KiB
Raw Blame History

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. fem-theory-query를 통한 FEM 이론 조사와 로컬 Abaqus User Subroutine Manual 근거 확인
  3. 코드 구현을 위한 유한요소 정식화
  4. Subroutine 입출력 파라미터와 Abaqus ABI 계약 정의
  5. TDD 방법을 사용하는 no-Abaqus test model 및 외부 생성 reference artifact 계약 작성
  6. Fortran 코드 구현
  7. references/<feature-id>/의 사용자 제공 CSV와 provenance artifact를 통한 결과 검증

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는 fem-theory-query와 로컬 Abaqus manual 원문을 사용하고, docs/research/<feature-id>-research.md에 source-backed fact, inference, applicability limit를 분리해 기록한다.
  • Formulation Agent와 Numerical Review Agent는 FEM 지식이 필요할 때 fem-theory-query를 사용하고 formulation, tangent, state variable, numerical risk를 구현 전 검토한다.
  • I/O Definition Agent는 로컬 Abaqus manual 원문을 근거로 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를 임의로 변경하지 않는다.

근거 탐색 규칙

  • 유한요소 정식화, residual/tangent, constitutive integration, benchmark, 수치 검증 등 FEM 관련 지식은 반드시 fem-theory-query를 통해 탐색한다.
  • Abaqus User Subroutine의 ABI, argument 의미, update responsibility, product applicability, utility routine은 먼저 docs/AbaqusUserSubroutineManual/INDEX_MAP.md에서 항목 위치를 찾고, INDEX.md의 해당 record를 읽은 뒤, record에 열거된 모든 source_ranges 원문을 순서대로 읽어 확인한다.
  • INDEX.md의 summary, keyword, content anchor는 탐색 metadata이며 구현 또는 interface 결정의 단독 근거가 아니다. 매뉴얼 source span을 authoritative evidence로 취급한다.
  • Solver-result verification은 사용자가 다른 Abaqus PC에서 생성해 첨부한 변위, 응력 또는 feature별 결과 CSV와 provenance metadata를 입력으로 사용한다.

작업 상태 공유 파일

  • 모든 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는 직접 파싱하지 않고, 사용자가 다른 Abaqus PC에서 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를 가져야 한다.
  • FEM 및 Abaqus manual 기반 claim은 사용한 skill 또는 manual section과 source span까지 추적 가능해야 한다.
  • 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한다.
Reference in New Issue View Git Blame Copy Permalink