Tesserae v0.28.3 — 추출기의 1턴 제한, 그리고 그것이 조용히 앗아간 것

<!-- translations:start -->

English · 中文 · 日本語 · Русский · Español · Français · Deutsch

<!-- translations:end -->

Released 2026-07-31 · PyPI · GitHub release · pip install --upgrade tesserae==0.28.3

플래그 하나. 첫 파이프라인 커밋 이래로 Claude 추출기에 계속 있었고, MCP 서버가 설정된 머신에서는 LLM 추출을 아예 동작하지 않게 만들었다 — 컴파일은 실패시키지 않은 채로.

--max-turns 1은 애초에 결정된 적이 없다

두 Claude CLI 호출 지점 모두 다음을 실행했다:

claude -p --output-format text --max-turns 1

--max-turns는 응답이 아니라 도구 호출을 센다. CLI의 설정 디렉터리에 MCP 서버나 훅이 있으면 모델의 첫 동작이 도구 호출일 수 있고, 그 순간 유일한 턴이 소진된다. 그러면 CLI는 JSON을 단 1바이트도 내보내지 못한 채 Reached max turns (1)과 함께 exit 1로 종료한다.

Tesserae는 이를 잡아내 결정론적 추출로 폴백한다. 프로바이더 장애가 컴파일 전체를 중단시켜서는 안 되기 때문이다. 그래서 컴파일은 성공했고, 그래프는 그럴듯해 보였으며, LLM은 아무것도 기여하지 않았다.

이 플래그는 선택된 적이 없다. 최초 파이프라인 커밋과 함께 들어왔고, 석 달 뒤 ClaudeCLIJsonClient가 그대로 복사했다 — docstring에 "run_claude_cli의 패턴을 따른다"고 적혀 있기 때문이다. 어느 커밋 메시지에도 이 플래그에 대한 언급은 없다.

원샷이 실제로 의미하는 것은 --strict-mcp-config다

턴 제한의 의도는 "한 번만 답하고 에이전트 루프를 돌지 마라"였다. 그것을 올바르게 표현하는 방법은 MCP 서버를 아예 로드하지 않는 것이다. 그러면 턴을 소모할 도구 자체가 없다:

claude -p --output-format text --strict-mcp-config

모델의 첫 응답이 곧 답이 되고, 설정된 MCP 서버가 호출을 굶길 수 없게 된다. 두 호출 지점 모두 수정되었으며, 회귀 테스트가 각 지점에서 턴 제한이 다시 돌아오지 않도록 검증한다.

이 문제가 당신의 그래프를 앗아갔는지 확인하는 법

이 실패는 컴파일 요약에는 보이지 않는다. 오직 로그에만 남는다:

grep -c 'Reached max turns' <컴파일 로그>

0보다 크다면 해당 파일들은 결정론적으로 추출된 것이며, 이 버전에서 다시 컴파일하면 복구된다. 이 프로젝트 자체 그래프에서는 진짜 LLM 추출을 되살리자 노드가 5,155개에서 13,182개로 늘었다 — 결정론적 폴백이 그래프의 약 60%를 앗아가고 있었다.

대부분의 파일에서 LLM 추출을 잃고도 컴파일이 성공을 보고한다는 점은 별개의 결함이며, #92에서 추적 중이고 이번 릴리스에서 고쳐지지 않았다. 이번 릴리스는 조용한 폴백의 원인 하나를 제거할 뿐, 그 조용함 자체를 없애지는 않는다.

v0.28.2에서 업그레이드

그대로 교체하면 된다. API·스키마·설정 변경 없음. 이전 컴파일이 영향을 받았다면 다시 컴파일해 놓쳤던 추출을 되찾으면 된다 — ~/.tesserae/llm_cache의 캐시된 LLM 응답은 재사용되므로, 폴백했던 파일만 비용이 든다.