diff --git a/docs/superpowers/specs/2026-08-18-project-guidance-refresh-design.md b/docs/superpowers/specs/2026-08-18-project-guidance-refresh-design.md new file mode 100644 index 0000000..5a7ed65 --- /dev/null +++ b/docs/superpowers/specs/2026-08-18-project-guidance-refresh-design.md @@ -0,0 +1,86 @@ +# 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과 테스트를 실행하지 않는다.