AbaqusSubroutineDev/docs/superpowers/specs/2026-08-18-project-guidance-refresh-design.md

Project Guidance Refresh Design

목적

Abaqus User Subroutine 개발 지침을 다음 세 원칙에 맞게 정비한다.

1. 유한요소 이론과 solver 지식은 fem-theory-query를 통해 조사한다.
2. Abaqus User Subroutine ABI와 매뉴얼 사실은 로컬 매뉴얼 index를 통해 찾는다.
3. 사용자가 폐기한 과거 feature에 종속된 산출물과 잔존 참조를 제거한다.

Abaqus 해석은 사용자가 다른 PC에서 수행하고, 이 저장소는 사용자가 첨부한 변위·응력 CSV와 provenance artifact를 schema/tolerance 기준으로 비교한다.

Source Routing

질문의 성격에 따라 근거 경로를 분리한다.

질문	필수 근거 경로
유한요소 정식화, residual/tangent, constitutive integration, benchmark, 수치 검증	fem-theory-query
Abaqus User Subroutine argument, update responsibility, product applicability, utility routine	docs/AbaqusUserSubroutineManual/INDEX_MAP.md → INDEX.md → 선택된 record의 모든 source_ranges
프로젝트 workflow와 artifact contract	AGENTS.md, docs/ABAQUS_SUBROUTINE_AGENT_DESIGN.md, docs/ARCHITECTURE.md, docs/ADR.md

INDEX.md의 summary와 keyword는 탐색 metadata로만 사용한다. 구현 또는 interface 결정을 내릴 때는 선택된 section의 모든 source span을 순서대로 읽고 원문을 authoritative source로 취급한다.

Verification Contract

• 기본 로컬 gate는 python scripts/validate_workspace.py이다.
• Fortran production 변경은 no-Abaqus Fortran/Python driver로 TDD 검증한다.
• Abaqus job과 ODB-to-CSV 추출은 사용자가 다른 Abaqus PC에서 수행한다.
• 사용자는 변위, 응력 또는 feature contract에서 지정한 결과 CSV와 provenance metadata를 제공한다.
• 이 저장소는 ODB를 직접 파싱하지 않고 CSV schema, matching key, unit, coordinate system, tolerance를 비교한다.

변경 범위

다음 파일에서 source routing과 CSV verification 경계를 일관되게 정리한다.

• AGENTS.md
• docs/PRD.md
• docs/ARCHITECTURE.md
• docs/ADR.md
• docs/ABAQUS_SUBROUTINE_AGENT_DESIGN.md
• docs/research/README.md
• FEM theory, Abaqus manual, reference CSV를 직접 다루는 .codex/agents/*.toml
• 관련 .codex/skills/*/SKILL.md와 변경된 skill의 agents/openai.yaml

새 매뉴얼 전용 skill은 만들지 않는다. 전역 AGENTS.md 규칙과 기존 research/interface skill에 index 탐색 절차를 추가하는 것이 더 단순하며 중복을 줄인다.

과거 Feature 제거 범위

이미 삭제된 사용자 변경을 보존하고, 남아 있는 versioned project-specific 항목을 제거한다.

• 과거 feature 전용 supplemental research brief
• 과거 feature 전용 research brief
• 과거 feature wrapper contract test
• scripts/test_validate_fortran.py에 남은 feature 전용 fixture 이름과 경로

공식 매뉴얼의 수치 적분 용어와 generic user-subroutine entry point 설명은 과거 feature 산출물이 아니므로 유지한다.

범위 제외

• Harness phase 생성 또는 실행
• Harness skill 사용
• Python, Fortran, workspace test 실행
• Abaqus job 실행 또는 ODB 직접 parsing
• CSV validator 구현 변경

정적 검증

테스트 대신 다음 문서 검사를 수행한다.

1. 변경 파일을 재독해 source routing과 verification 계약의 충돌을 확인한다.
2. versioned 파일에서 폐기된 feature의 식별자와 전용 설명이 남지 않았는지 검색한다.
3. 변경된 skill frontmatter와 agents/openai.yaml의 의미가 일치하는지 확인한다.
4. git diff --check와 diff 검토만 수행한다.

성공 기준

• FEM 관련 지식 탐색이 fem-theory-query로 명시된다.
• Abaqus 매뉴얼 사용 순서가 INDEX_MAP.md → INDEX.md → 모든 source_ranges로 명시된다.
• 외부 Abaqus PC에서 생성한 변위·응력 CSV 비교가 유일한 solver-result verification 경로로 유지된다.
• 폐기된 project-specific feature 파일과 versioned 참조가 남지 않는다.
• 기존 사용자 변경을 되돌리지 않는다.
• Harness skill과 테스트를 실행하지 않는다.