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에서 확보 여부·현행 시행일을 먼저 확인한다 (구경로 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. 파일 템플릿

---
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의 시행일과 이 폴더 각 파일 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 갱신 관리 (2026-08-15 이관 — 이 문서에는 절차만 남기고 주기·기준일·다음 확인 시점은 §10에서 단일 관리한다. 재검토기한 경과 고시 목록도 §10에 있음).

7. 프로그램 연계

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