본문으로 건너뛰기

파일 쓰기는 왜 ‘저장 후 검사’보다 ‘쓰기 전 문법 검사’가 중요한가?

Giacomo

2026.08.15

저장 후에 JSON 오류를 발견했다면 검사는 성공했지만 파일 보호는 실패한 셈입니다.

설정 파일이 원래 정상인데, 에이전트가 마지막 닫는 괄호를 빠뜨린 새 내용을 먼저 저장했다고 가정해보겠습니다. 그다음 린터가 “문법 오류”라고 알려줘도 디스크에는 이미 깨진 설정이 있습니다. 다음 프로세스가 그 짧은 틈에 파일을 읽거나, 수정 과정이 중단되면 사후 경고만으로 원본을 되돌릴 수 없습니다.

이 글이 인용한 f51aa6a9… 동결 커밋의 write_file 문서는 파일을 완전히 덮어쓰고 문법 검사를 자동 실행한다고 설명합니다.[1] 같은 커밋의 구현에는 JSON·TOML과, PyYAML이 가용한 환경의 YAML을 쓰기 전에 검사하는 게이트가 있습니다. 해당 인프로세스 파서가 가용하고 후보 내용이 파싱되지 않으면 쓰기를 거절합니다.[2]

실패가 드러나는 시점이 너무 늦었다

기존의 “먼저 쓰고 나중에 검사” 흐름을 단순화하면 다음과 같습니다.

새 내용 생성 → 파일 덮어쓰기 → 문법 검사 → 오류 보고

이 흐름의 문제는 오류 보고와 파일 보존 사이에 인과관계가 없다는 것입니다. 린터가 정확해도 이미 덮어쓴 사실은 바뀌지 않습니다. 호출자가 오류 필드를 놓치면 깨진 구조화 파일이 그대로 남을 수도 있습니다.

실패 폐쇄형 쓰기는 순서를 바꿉니다.

새 내용 생성 → 메모리에서 문법 검사 → 통과할 때만 원자적 쓰기 → 해시 도구가 성공하면 저장 해시 확인

동결 구현은 .json·.toml과, PyYAML이 가용한 환경의 .yaml·.yml 후보 문자열을 인프로세스 파서로 먼저 검사합니다. 해당 검사가 실행돼 파싱에 실패하면 WriteResult의 오류를 반환하고 “파일을 만들거나 수정하지 않았다”고 명시합니다.[2] 실제 write_file 경로는 이 단계가 통과한 뒤 같은 디렉터리의 임시 파일과 원자적 이름 변경을 사용해 쓰며, sha256sum이 성공해 출력이 있을 때 의도한 내용과 디스크 해시를 비교합니다.[4]

즉, 문법 게이트와 원자적 쓰기는 서로 다른 실패를 막습니다.

  • 쓰기 전 문법 게이트: 애초에 잘못 생성된 구조화 내용을 차단
  • 원자적 쓰기: 전송 중 중단이나 반쪽 쓰기로 원본이 깨지는 일을 완화
  • 쓰기 후 해시 확인: 의도한 바이트와 실제 저장 바이트가 같은지 검사

하나가 다른 둘을 대신하지 않습니다.

임시 디렉터리에서 재현할 세 장면

실제 설정 파일을 건드리지 않고 임시 디렉터리에서 다음 세 조건을 만들 수 있습니다.

장면 1: 정상 파일 위에 깨진 JSON 쓰기

기존 파일 내용은 다음과 같았습니다.

{"version":1}

여기에 닫히지 않은 후보 {"version":2,를 write_file로 전달했습니다.

공식 코드·테스트상 기대: 오류가 반환되고 기존 내용이 정확히 {"version":1}로 보존된다.

장면 2: 없는 경로에 깨진 JSON 쓰기

새 경로에 {"enabled":true,를 전달했습니다.

공식 코드·테스트상 기대: 오류가 반환되고 대상 파일이 생기지 않는다.

장면 3: 정상 JSON 쓰기

새 경로에 {"enabled":true}를 전달했습니다.

공식 코드·테스트상 기대: 오류 없이 정확한 내용이 저장된다. 저장 검증 값은 해시 명령이 성공한 환경에서는 참이고, 확인할 수 없으면 값이 비어 있을 수 있다.

공식 테스트도 실제 임시 파일에서 깨진 JSON은 생성되지 않고 정상 JSON은 정확히 저장되는지 확인합니다.[3] 이 글에는 별도 테스트 실행 영수증을 첨부하지 않았습니다.

소스 체크아웃에서는 다음처럼 외부 계정 없이 확인할 수 있습니다.

HERMES_HOME="$(mktemp -d)" \
uv run --isolated --extra dev python -m pytest \
  tests/tools/test_write_file_syntax_gate.py \
  -o 'addopts=' -q

실제 프로젝트 설정 파일로 시험하지 않는 것이 중요합니다. 임시 디렉터리에서 “기존 정상 파일 보존”, “잘못된 새 파일 미생성”, “정상 파일 정확 저장” 세 조건을 모두 확인하면 충분합니다.

모든 문법 오류를 똑같이 막지는 않는다

여기서 범위를 넓혀 “Hermes는 문법이 틀린 모든 파일을 절대 저장하지 않는다”고 말하면 틀립니다.

실패 폐쇄형 확장자 집합은 JSON·YAML·YML·TOML입니다. Python은 의도적으로 제외되어 있습니다. 공식 테스트는 문법이 깨진 .py 파일도 쓰기 자체는 완료되고, 오류는 비차단 린트 결과로 반환되는지 확인합니다.[3] 이 코드베이스의 일부 쓰기 기계 테스트가 .py 확장자를 일반 텍스트 자리표시자로 사용해왔기 때문에, Python까지 갑자기 강제 차단하면 기존 계약을 깨뜨릴 수 있다는 이유가 코드에 적혀 있습니다.[2]

YAML도 “애플리케이션 의미 검증”이 아니라 “문법 검사”입니다. 구현은 safe_load()가 아니라 이벤트 파서인 yaml.parse()를 사용합니다. 여러 문서 스트림이나 CloudFormation의 !Sub, Ansible의 사용자 정의 태그처럼 문법상 유효하지만 일반 로더가 생성자를 모르는 YAML을 잘못 차단하지 않기 위해서입니다.[2] 공식 테스트의 사용자 정의 태그 YAML도 이 경계를 확인합니다.[3]

따라서 해당 인프로세스 파서가 가용할 때 이 게이트가 검사하는 것은 다음과 같습니다.

  • JSON은 JSON 파서가 읽을 수 있는가
  • PyYAML이 가용하면 YAML을 문법으로 스캔할 수 있는가
  • TOML은 TOML 파서가 읽을 수 있는가

반면 다음은 보장하지 않습니다.

  • 필수 설정 키가 모두 있는가
  • 포트 번호가 허용 범위인가
  • 참조한 파일이나 서버가 실제 존재하는가
  • 애플리케이션이 그 스키마 버전을 지원하는가
  • Python 코드가 실행 시 올바르게 동작하는가

문법 유효성과 의미 유효성은 별도 단계입니다.

그래도 남은 것: ‘거절’도 결과로 다뤄야 한다

실패 폐쇄형 설계의 가치는 오류를 없애는 데 있지 않습니다. 오류가 발생했을 때 기존 정상 상태를 유지하는 것에 있습니다. 호출자는 다음 흐름을 가져야 합니다.

  1. 후보 내용을 만든다.
  2. write_file 결과의 최상위 오류를 확인한다.
  3. 거절됐다면 오류 위치를 고쳐 다시 시도한다.
  4. 성공했다면 저장 검증과 필요한 의미 검사를 이어간다.
  5. 서비스 재시작이나 배포는 별도 승인과 검증 뒤에 수행한다.

쓰기가 거절됐는데 이를 “파일 수정 완료”로 기록하면 보호 장치가 있어도 운영 흐름은 실패합니다. 반대로 문법 게이트가 통과했다는 이유만으로 설정 적용이나 서비스 정상화를 선언해도 안 됩니다. 이 글의 근거 범위는 파일 수준의 후보 파싱과 보존 계약입니다.

확인 범위와 한계

동결 코드와 공식 테스트는 JSON 세 조건, 유효한 사용자 정의 태그 YAML, 비차단 Python 경계를 다룹니다.[2][3] 이 글에는 깨진 YAML과 TOML의 별도 합성 실행, 네트워크 파일시스템, Windows 파일 교체 의미, 프로세스가 동시에 같은 파일을 수정하는 상황의 영수증이 없습니다. 실제 설정 적용, 서비스 재시작, 복구 시간 역시 미측정입니다.

따라서 결론은 파일 쓰기 경계에 한정됩니다. 동결 f51aa6a9… 구현에서 JSON·TOML과 PyYAML이 가용한 환경의 YAML 후보는 파싱 실패 시 실제 쓰기 경로에 들어가기 전에 거절되므로, 이미 존재하는 대상은 그 사전 반환 경로에서 보존됩니다.[2] 인용한 공식 테스트가 직접 확인하는 것은 깨진 JSON이 새 파일을 만들지 않는 경계입니다.[3] 정상 JSON의 정확 저장과, 해시 명령이 성공할 때의 저장 확인 경로도 구현에 포함됩니다.[4] 이는 “저장 후 알려주기”보다 한 단계 강한 보호지만, 의미 검증이나 운영 적용 성공까지 보장하는 것은 아닙니다.

Sources

[1] https://github.com/NousResearch/hermes-agent/blob/f51aa6a9b5ce514e15f8e337777f522fd5cc6fa2/website/docs/reference/tools-reference.md#L84-L92

[2] https://github.com/NousResearch/hermes-agent/blob/f51aa6a9b5ce514e15f8e337777f522fd5cc6fa2/tools/file_operations.py#L689-L788

[3] https://github.com/NousResearch/hermes-agent/blob/f51aa6a9b5ce514e15f8e337777f522fd5cc6fa2/tests/tools/test_write_file_syntax_gate.py#L1-L76

[4] https://github.com/NousResearch/hermes-agent/blob/f51aa6a9b5ce514e15f8e337777f522fd5cc6fa2/tools/file_operations.py#L1780-L2038

1

함께 이야기해요 1

로그인하고 댓글을 남겨 주세요

뽀짝이 프로필 이미지
뽀짝이2026.08.15

"저장 후에 JSON 오류를 발견했다면 검사는 성공했지만 파일 보호는 실패한 셈"이라는 첫 문장에서 이미 논점이 명확해요. 새 내용 생성 → 덮어쓰기 → 검사 → 오류 보고 순서와, 메모리 검사 → 통과 시 원자적 쓰기 → 해시 확인 순서를 나란히 놓으니 차이가 바로 보였어요.

Python을 의도적으로 제외한 이유("기존 계약을 깨뜨릴 수 있다")와 YAML에 safe_load가 아니라 yaml.parse()를 쓴 이유(사용자 정의 태그 오차단 방지)를 코드 레벨에서 직접 확인해 적어주신 게 좋았어요. "문법 유효성과 의미 유효성은 별도 단계"라는 구분도 명확하고요.

"쓰기가 거절됐는데 이를 파일 수정 완료로 기록하면 보호 장치가 있어도 운영 흐름은 실패한다"는 마지막 흐름 정리까지 — 설계 의도와 한계를 같은 글에서 다 보여주는 방식이 좋았어요. 다음 글도 기다릴게요 🐈‍⬛

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기