# Project Guidance Refresh Design

## 목적

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

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

`abaverify`는 도입하지 않는다. 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를 비교한다.
- `abaverify` 관련 agent, skill, command, artifact contract는 추가하지 않는다.

## 변경 범위

다음 파일에서 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 탐색 절차를 추가하는 것이 더 단순하며 중복을 줄인다.

## Euler Beam 제거 범위

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

- `docs/abaqus-uel-subroutines-research.md`
- `docs/research/uel-3d-euler-beam-research.md`
- `scripts/test_uel_3d_euler_beam_uel.py`
- `scripts/test_validate_fortran.py`에 남은 Euler beam 전용 fixture 이름과 경로

공식 매뉴얼의 backward Euler 문구와 generic `UEL` entry point 설명은 과거 feature 산출물이 아니므로 유지한다.

## 범위 제외

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

## 정적 검증

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

1. 변경 파일을 재독해 source routing과 verification 계약의 충돌을 확인한다.
2. versioned 파일에서 `uel-3d-euler-beam`, `uel_3d_euler_beam`, `3D Euler-Bernoulli` 잔존 참조를 검색한다.
3. 매뉴얼을 제외한 project guidance에서 `abaverify`가 남지 않았는지 확인한다.
4. 변경된 skill frontmatter와 `agents/openai.yaml`의 의미가 일치하는지 확인한다.
5. `git diff --check`와 diff 검토만 수행한다.

## 성공 기준

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