Aislo/resources/knowledge/00_운영지침.md

# technical_info 운영지침

> 이 폴더는 Aislo 프로그램의 설계 로직·검증 기준의 근거가 되는 **기술문서(파생 요약본)** 저장소다.
> `original/`(불변 원본)과 달리 이 폴더는 AI가 생성·갱신한다. raw/ 불변 규칙의 예외 폴더.

> **★★ 지식DB 역할 원칙 (2026-08-13 사용자 확정)**: 이 지식저장소는 **객관적 근거값을 수집·정리해 개발 과정에서 사용자와 협의하여 합리적 선택을 하도록 돕는 가이드**다. **값을 확정하는 영역이 아니다.** 문서에 "기본값 채택·잠정 채택·권장" 류의 단정 서술 금지 — 근거별 후보를 병기하고 선정은 개발 단계 사용자 협의로 넘긴다. 선정된 값은 법령·행정규칙·교본 개정 시 갱신되도록 원문 버전과 연동해 관리한다.
>
> **★★ 교본 사업 매칭 원칙 (2026-08-13 사용자 확정)**: 임도기술교본은 **임도**, 사방기술교본은 **사방**을 주 대상으로 본다. 자기 사업 교본에 내용이 누락된 경우 상대 교본을 **참조할 수 있으나 확정값이 될 수 없다**(반대 방향도 동일). 교차 참조 시 문서에 출처 교본과 "교차 참조 — 확정값 아님"을 명시한다.
>
> **★ 근본 원칙 (프로그램 설계 기준)**: Aislo 프로그램의 기본값·계산 로직은 **현행 법령·행정규칙 기준으로 설계**한다. `original/실무문서/`(공사지 설계 산출물)는 특정 설계연도의 **과거 데이터**이며, 설계자마다 로직이 달라 결과적으로 **참조·검증용**일 뿐 설계 기준이 아니다. 실무값이 현행 범위를 벗어나면 **현행이 우선**한다. 실무는 "현행 기준을 이렇게 적용한 사례"로만 취급하며, 최종 기본값·예외는 개발 과정에서 사용자가 확정한다. 단, **현행에 규정이 없는 공백 영역**(예: 구조물 표준도 원단위, 도달시간 세부식)은 실무 관측값을 **채용 후보(제안)**로 둘 수 있다 — 이 경우에도 확정은 사용자. → 실무 종합비교는 `original/실무문서/_종합비교/`, 이 원칙이 그 문서들과 이 기술문서(메인)를 잇는 축이다.

## 1. 목적

- `original/` 원문(법률·행정규칙·표준시방서·KS·임도기술교본)을 근거로 임도 설계에 필요한 기준·계산식·시공방법을 요약 정리한다.
- 정리된 문서는 Aislo 프로그램의 계산 로직 구현과 결과 검증의 기준으로 사용한다.
- 독자는 AI다. 미사여구 없이 수치·조건·식·표 중심으로 작성한다.
- 작성된 기술문서는 향후 `original/실무문서/` 파일들과 대조하여 검증한다 (실무=대조 데이터, 기준 아님 — ★근본 원칙).
  - `original/실무문서/`는 다른 프로그램으로 설계한 결과물이며, 기술문서의 적합성을 따지기 위한 **비교 검증용 데이터**다.
  - ⚠ **경고**: 실무문서는 사람이 작성한 결과물이라 문서마다 적용 로직이 서로 다를 수 있다. 기술문서와 실무문서가 불일치해도 기술문서 오류로 단정하지 말 것. 불일치 발견 시 판정하지 말고 기록 후 **사용자 수작업 확인**을 요청한다.

## 2. 소스 및 우선순위

근거 충돌 시 상위 소스를 채택한다.

| 순위 | 소스 | 위치 | 성격 |
|---|---|---|---|
| 1 | 법률 > 시행령 > 시행규칙 (별표 포함) — 산림자원법(임도)·사방사업법(사방) | `original/법률/` | 법적 강제 |
| 2 | 행정규칙 (훈령·예규·고시) — 임도설치 및 관리 등에 관한 규정, 사방사업의 설계·시공 세부기준 등 | `original/행정규칙/` | 행정 기준 |
| 3 | 표준시방서 (임도시설공사·KCS) | `original/표준시방서/` | 시공 기준 |
| 4 | KS 표준 | `original/KS/` | 재료·시험 기준 |
| 5 | 임도기술교본(2020)·사방기술교본(2023) | `original/임도기술교본/`·`original/사방기술교본/` | 해설·실무 (법적 구속력 없음, 단 수치가 가장 상세) |

- 원문 참조 시 [`04_참조_법령기준_목록.md`](04_참조_법령기준_목록.md)에서 확보 여부·현행 시행일을 먼저 확인한다 (구경로 `original/0. 참조 법령·기준 목록.md` — 2026-08-15 이동 정정).
- 법령은 **현행본**(`현행_YYYYMMDD.md`)을 기준으로 한다. 교본시점 판본은 대조용으로만 쓴다.
- 교본 내용이 현행 법령·규정과 다르면 현행을 채택하고 문서에 차이를 명시한다.

## 3. 파일 구성 원칙

- **1파일 = 1구조물 또는 1계산방식.** 예: 횡단배수관, 토량계산, 돌쌓기.
- 파일에는 해당 주제의 ① 설계 기준(수치·조건) ② 계산 방법(식·변수·단위) ③ 시공 방법(프로그램 검증에 필요한 범위만) ④ 근거 출처를 담는다.
- 최상위는 **사업 트리 2개**로 완전 분리한다: `01_임도/`(현행) · `02_사방댐/`(설계자동화 확장). 각 트리는 같은 역할 그룹 5개 체계를 쓴다. 구조는 `_index.md`에서 관리한다.
  - `01_임도/01_계획노선/` — 임도망 편성·노선 배치·타당성평가 등 **계획 노선** 영역. 프로그램 반영은 2027년 예정이나 기술문서 수립은 지금 병행한다.
  - `01_임도/02_상세설계/` — **공사지 기준 상세설계** 영역. 현시점 프로그램의 주 대상이며 분량도 가장 많다.
  - `01_임도/03_계산정보/` `01_임도/04_수량분석정보/` `01_임도/05_원가정보/`
  - `02_사방댐/01_대상지_타당성평가/` — 사방은 "노선"이 아닌 **대상지** 개념(사방기술교본 총론 4장 "대상지 실태조사 및 타당성 평가"). 이하 `02_상세설계/`~`05_원가정보/`는 임도와 동일 체계.
  - 계획(대상지)과 상세설계는 내용이 섞이지 않도록 반드시 구분해 작성한다.
- **사업 트리 간 중복 처리 원칙**: 사업 무관 공통 내용(콘크리트 재료·양생, 토량환산 L·C, 품셈 총칙·할증, 원가 제비율 등)은 **임도 문서가 1차 정의** — 사방댐 문서는 링크 참조 + 사방 차이점만 기술한다. 이름이 같아도 기준이 다른 항목(예: 설계유량 — 임도 KDS 100년빈도·2.0배 vs 사방 합리식·방수로 여유고)은 각자 작성한다.
- `03_미결_및_확인사항.md`는 두 트리 공용 — 항목에 **[임도]/[사방]** 구분을 붙여 한 파일에서 이력 관리한다.
- **구조물**(돌쌓기·흙막이·골막이·옹벽 등)은 종류·변수·적용 케이스가 방대하므로 집중 분석 대상이다. `01_임도/02_상세설계/구조물/` 하위 폴더로 분리하고, 작성 시 변수·케이스를 전수 정리하며 필요하면 파일을 추가 분할한다.
- 역할 그룹 간 내용이 겹치면 **중복 작성하지 않고 상호 링크**로 연결한다. 단, 링크 누락으로 인한 정보 누락은 금지 — 어느 그룹에서 출발해도 관련 기준·식·수량·원가에 도달할 수 있어야 한다.
- 700줄 제한은 **소스코드 규칙**으로 기술문서에는 적용하지 않는다 (사용자 확인 2026-08-12). 문서 분할은 줄 수가 아니라 주제 단위 가독성으로 판단한다.

## 4. 파일 템플릿

```markdown
---
title: <주제명>
category: <폴더 그룹명>
sources:
  - doc: <원문 명칭>
    version: <시행일 YYYY.MM.DD 또는 판본>
    loc: <original/ 상대경로 또는 조문·별표 번호>
status: draft | verified | approved | exported   # 4단계 — 아래 '문서 승인 상태' 참조
last_updated: YYYY-MM-DD
---

## 설계 기준
(수치·조건. 표 우선)

## 계산 방법
(식은 LaTeX 또는 코드블록. 변수 정의·단위 필수)

## 시공 방법
(프로그램 로직·검증에 필요한 범위만)

## 근거
| 항목 | 출처 | 조문/절 |
|---|---|---|
```

### 문서 승인 상태 (status) — 4단계 (2026-08-15 도입, 구 draft|confirmed 대체)

| 단계 | 의미 | 승격 조건 |
|---|---|---|
| `draft` | 작성됨 — 원문 검증 전 | (초기값) |
| `verified` | **원문 검증 완료** — 수치·조문 1:1 대조 통과, _최종검증로그에 기록 | 검증 세션에서 원문 대조 통과 |
| `approved` | **사용자 승인** — 기본값 선정 협의까지 완료 (미결·selection pending 없음) | 사용자 검토·확정 |
| `exported` | **JSON 반영 완료** — data_cost_input_value 등 프로그램 데이터로 생성됨 | 데이터 생성 + 해시 등록 |

- 강등 규칙: 인용 원문이 개정·수정되면 해당 문서는 `verified` 이상이라도 **`draft`로 강등** 후 재검증 (검증 결과 자동 무효화 원칙).
- 승격은 건너뛰지 않는다 (draft→approved 불가). 단 JSON 대상이 아닌 문서는 `approved`가 최종.
- 기존 문서 65건은 전부 `draft` 유지 — 검증 세션에서 통과분부터 개별 승격 (일괄 변경 금지: 검증 없이 상태만 올리는 것 방지).

## 5. 작성 규칙

- 서술 최소화. 표·목록·식 위주. AI가 재분석하기 쉬운 구조.
- 수치는 반드시 단위와 함께. 범위 값은 하한~상한 명시.
- 수치·기준이 1차 근거이나, 법률·지침 조문이 애매모호한 경우가 있으므로 **요약 설명을 함께 작성**한다. 향후 AI가 문서만 읽고 취지를 오해하지 않도록 한다.
  - 원문 수치·조문: 해석 없이 그대로.
  - 조문 취지·적용 조건 요약: `> [해석]` 인용문으로 구분.
  - 프로그램 구현 관점 주석: `> [구현]` 인용문으로 구분.
- 근거 없는 내용 작성 금지. 모든 수치·식은 출처 명시. 추측으로 채우지 않는다 — 근거를 못 찾으면 `⚠ 근거 미확인`으로 표기하고 남긴다 (할루시네이션 방지).
- 간선임도/지선임도/작업임도 구분이 있는 기준은 반드시 구분해 기재.
- **KS 원문**: 미확보(DRM) 상태로 진행한다. 대부분 시험 방법 관련으로 설계 로직과 무관할 확률이 높다. 작성 중 KS 원문 수치가 반드시 필요한 경우 해당 문서에 `⚠ KS 원문 필요`로 표기하고, `KS_필요목록.md`에 규격번호·필요 사유·대상 문서를 기록한다. 원문은 사용자가 확보해 넣어준다.

### ★ 원문 인용 4원칙 (2026-08-14 전역 감사 결과 — 오류 30건의 공통 원인)

감사에서 드러난 오류는 대부분 "값을 틀리게 옮긴 것"이 아니라 **원문을 요약하면서
정보를 버린 것**이었다. 다음 4가지를 인용 시마다 지킨다.

1. **범위·구분을 단일값으로 축약 금지.** 원문이 "2~3㎡당 1개소 이상"이면 그대로 쓴다
   ("2㎡당 1개" ✕). 용도·조건별로 값이 갈리면 전 구간을 옮긴다
   (예: 모래 할증 = 잔골재 10/12 · 노반 6 · 관류기초 4 %, "10 %" 단일 기재 ✕).
2. **조건 단서를 함께 옮긴다.** 제외 규정·예외·적용 하한은 값의 일부다
   (예: 암석작업 손료 보정 +25 % ← "전용덤프트럭 18톤 이상·불도저 19톤 이상 제외,
   단 타이어·습지 불도저는 보정").
3. **법률은 본문 조항만 보지 않는다.** 요율·금액·기준은 **부칙 특례·경과조치**에서
   연도별로 달라지는 경우가 있다 (국민연금 4.75 % = 부칙 §4, 본문 §88③은 6.5 %).
   법률 인용 시 같은 폴더의 **현행_*.xml 을 직접 확인**한다. 조달청 제비율표 등
   실무 요율표가 있으면 **교차 대조**한다.
4. **교본값을 "현행"으로 쓰지 않는다.** 교본(임도 2019·사방 2023)은 참고이고 현행
   기준은 법령·훈령·고시다. 값이 다르면 현행을 쓰고 교본값은 "구 기준"으로 병기한다
   (예: 국가지점번호판 간격 = 훈령 500 m, 교본 1 ㎞ ✕).

인용한 원문 md 자체가 표·조항을 생략하고 있으면(“원본 xlsx 참조” 등) 그 md를 근거로
삼지 말고 **첨부 원본(xlsx·PDF·XML)에서 값을 확인한 뒤 원문 md도 함께 보완**한다.

## 6. 업데이트 절차

법령·행정규칙 개정 시:

1. `original/`에 신규 현행본 수집 (원본 갱신은 별도 작업).
2. [`04_참조_법령기준_목록.md`](04_참조_법령기준_목록.md)의 시행일과 이 폴더 각 파일 frontmatter `sources.version` 대조.
3. 버전 불일치 파일을 찾아 내용 갱신, `last_updated` 갱신.
4. 수치·기준이 변경된 경우 문서 하단에 `## 개정 이력` 절을 만들어 변경 전후 값 기록 (프로그램 로직 수정 필요 여부 판단용).
5. 갱신 결과를 `_index.md`에 반영.
6. 법령 md 를 새로 받았거나 변환 규칙이 바뀌면 `original/_pipeline/patch_law_md.py` 로
   **부칙·목 누락분을 보충**한다 (전량 재생성은 후처리를 파괴하므로 금지 — 상세는
   `original/_pipeline/README.md`).

### 갱신 주기가 정해진 원천

갱신주기표의 SSOT = [04_참조_법령기준_목록 §10 갱신 관리](04_참조_법령기준_목록.md)
(2026-08-15 이관 — 이 문서에는 절차만 남기고 주기·기준일·다음 확인 시점은 §10에서
단일 관리한다. 재검토기한 경과 고시 목록도 §10에 있음).

## 7. 프로그램 연계

- Aislo 계산 로직 구현 시 이 폴더 문서를 스펙으로 사용한다. 코드 주석에 참조 파일명 기재 권장.
- 문서와 코드가 불일치하면 문서(현행 법령 근거)를 우선하고 코드를 수정한다.
- **설계 기준 = 현행법**(★근본 원칙). 실무문서 값은 스펙이 아니라 참조·검증용이다. 실무 종합비교(`original/실무문서/_종합비교/`)의 ④ Aislo 제안값은 **제안·참고**이며, 현행 범위와 충돌하면 현행을 채택한다. 각 기술문서는 관련 종합비교 주제(01~06)를 검증 근거로 역참조하되(`## 실무 검증 참조` 섹션), 기본값은 현행 조문·별표에서 확정한다. 현행 공백 항목은 실무 라이브러리를 제안값 후보로 두고 사용자가 확정한다.
- `status: draft` 문서는 원문 검증 전이므로 로직 구현 근거로 쓰기 전 확인 필요. 프로그램 기준값 배포는 `approved` 이상, 데이터 파일 연동은 `exported`만 신뢰 (§4 문서 승인 상태 참조).