FESADev/docs/development-context.md

기능 개발 문서와 컨텍스트 예상량

2026-10-18 작업 트리의 UTF-8 텍스트를 기준으로 한 대략값이다. 모델별 tokenizer 실측이 아니며 대화·시스템 지침·도구 정의·새 로그·작성 중인 코드와 답변은 포함하지 않는다. 같은 자료를 다시 출력하면 그만큼 더 사용하므로 아래 표는 파일을 한 번씩 읽는 경우다.

작업별 문서 묶음

먼저 기능 색인의 변경별 읽기 범위에 따라 필요한 자료를 선택한다. 루트 지침은 읽기 묶음마다 한 번만 계산하며 AGENTS.md와 동일한 CLAUDE.md를 중복 합산하지 않는다. 저장소의 지침24개를 모두 읽는 대신 실제 변경 경로의 상위 지침과 관련 영역 지침을 선택한다.

읽는 범위	예상 토큰
루트 AGENTS.md 하나	약 2천~4천
루트 → src/fesa → analysis 지침 한 경로	약 3천~6천
일반 beam C++ 개발 문서	약 6천~1만2천
위 문서와 beam formulation 원문 전체	약 1만8천~3만4천
HHT 현행 수식 문서 묶음 전체	약 2만9천~5만4천
일반 beam 개발 문서와 아래 소스·테스트3개 전체	약 2만2천~3만8천

일반 beam 묶음은 루트 지침·색인·beam README, include/fesa·src/fesa·elements·tests 지침과 solver-core의 개발 교훈·검증 경계 절이다. 수식 변경 예시는 책임·수명 절과 formulation 전체를 추가했다. API·I/O·빌드가 바뀌면 해당 공통 절과 consumer를 더 확인해야 한다.

HHT 묶음은 관련 기본 지침·README·공통 수명/검증 절과 현행 관성·축소 좌표·고정 null 기저· carried-A noise 원문이다. 과거 full-coordinate/consistent 수식과 미채택 연구까지 일괄 포함한 값은 아니다. 실제 변경에 해당하는 절만 읽으면 원문 전체를 읽는 예시보다 줄일 수 있다.

소스 포함 예시는 공개 beam header, beam 구현, 요소 테스트 전체를 읽는 경우다. 다른 기능의 소스·테스트·실행 출력 크기는 다르므로 이 값을 전체 기능의 고정 예산으로 쓰지 않는다.

기존의 공통 요약 전체를 기본 필독으로 읽던 같은 beam 예시는 약 9천1만7천 토큰이었다. 관련 절을 고르는 현재 안내는 그 예시의 중간 추정량을 약 2530% 줄인다. 수식과 검증 기준을 삭제해서 얻는 감소가 아니며, 코드·도구 출력까지 포함한 전체 세션의 절감률도 아니다.

통째로 읽을 때 큰 자료

자료	예상 토큰
현재 관리 Markdown64개, 생성물·보관본 제외, CLAUDE 중복·조건부 스킬 포함	약 18만~34만
병합 manifest JSON + 테스트 이관 TSV, 약4.74MB	추가 약 100만~168만

Manifest는 초기 목록과 후속 단계의 검증을 누적한 감사 자료다. 필요한 key를 선택하고, 이관표는 original_identity·final_identity·final_path 등으로 해당 행만 찾는다. 전체 자료를 기본 개발 컨텍스트로 넣지 않는다. 상세 수식·역사적 연구는 관련 쟁점을 검토할 때 읽으며, 과거 PASS와 미검증 범위는 각 기능 README에서 확인한다.

추정 방법과 한계

실제 문자 수를 ASCII·한글 음절/자모·기타 Unicode로 나눴다. ASCII는 35문자당1토큰, 한글은 문자당12토큰, 기타 문자는0.5~2토큰이라는 넓은 가정으로 범위를 계산했다. 중간값은 각각4문자당1·문자당1.5·문자당1로 두었다. 이 계수는 예측을 위한 가정이며 특정 모델의 토큰 분할 규칙이 아니다. 영어 식별자·LaTeX·숫자·한글 혼합 비율에 따라 달라진다.

실제 세션에는 사용자 요청·이전 대화·플랫폼 지침과 도구 결과가 더해진다. 문서 추정량을 모델의 전체 context 한도나 요금으로 해석하지 않는다. 큰 테스트 파일·JSON·반복 실행 로그는 필요한 구간을 먼저 검색하고, 수식 변경에는 관련 유도·가정·실패 경계와 독립 검증을 생략하지 않는다.