agent-file-lock (afl)은 코딩 에이전트(coding agent)나 사용자에 의해 중요한 파일이 임의로 수정, 삭제, 혹은 이름이 변경되는 것을 방지하기 위해 설계된 도구입니다. 이 도구는 파일 시스템의 커널 레벨 속성을 활용하여 강력한 보호 기능을 제공합니다.

1. 핵심 방법론 및 기술적 메커니즘

afl은 단순히 파일 권한(chmod)을 수정하는 방식을 넘어, 커널이 직접 관리하는 불변성(immutability) 속성을 이용합니다.

• Strong Level (Default): Linux에서는 FS_IMMUTABLE_FL (chattr +i), macOS에서는 SF_IMMUTABLE (chflags schg)을 사용하여 파일의 내용을 수정하거나 삭제하는 것을 원천 차단합니다. 이는 루트(root) 권한 없이는 해제가 불가능합니다.
• User Level: Linux의 chmod a-w 또는 macOS의 UF_IMMUTABLE을 사용합니다. 일반 사용자 권한으로도 설정을 되돌릴 수 있으나, 시스템 설정에 따라 유연하게 활용 가능합니다.
• Parent Guards (부모 디렉토리 보호): 파일 자체를 잠그는 것만으로는 에이전트가 "파일을 포함한 상위 디렉토리를 통째로 이름 변경(Rename)"하여 우회할 위험이 있습니다. 이를 방지하기 위해 afl은 파일부터 프로젝트 루트까지의 모든 부모 디렉토리에 대해 append-only 속성(FS_APPEND_FL / SF_APPEND)을 부여합니다. 이를 통해 기존 파일이나 디렉토리의 삭제 및 이름 변경을 차단하면서도, 새로운 파일을 생성하는 작업은 허용합니다.

2. 에이전트 연동 및 보안 제어

afl은 단순히 EPERM(Operation not permitted) 오류를 발생시켜 에이전트가 에러를 오판하게 만드는 대신, PreToolUse hook을 제공합니다.

• Hook Mechanism: 에이전트가 특정 도구를 호출하기 전, afl hook이 이를 가로채어 실행하려는 명령어가 잠긴 파일에 접근하는지 분석합니다. 만약 접근 시도 시, "사용자가 해당 파일 수정을 허용하지 않음"이라는 명확한 메시지를 전달하여 에이전트의 우회 시도를 방지합니다.
• 통신 규격: stdin을 통해 JSON 형태의 도구 호출 정보를 입력받으며, exit code 2를 통해 차단 여부를 알립니다. tool_name, tool_input, cwd 등을 분석하여 mv, rm, sed -i 등의 위험한 작업을 식별합니다.

3. 주요 기능 및 운영

• afl run: git pull 등 잠금 파일이 포함된 작업을 수행해야 할 경우, afl run 명령어를 통해 일시적으로 보호를 해제하고 작업을 마친 뒤 자동으로 다시 잠금을 설정합니다.
• afl status/check: 현재 디렉토리 트리 내에서 잠긴 파일과 보호 중인 디렉토리를 스캔하거나, CI 환경에서 설정 파일(afl.yaml) 대비 파일 상태가 변경(drift)되었는지 검사합니다.
• 확장성: 단일 정적 Go 바이너리로 제공되며, 별도의 런타임 의존성이 없습니다. Claude Code 및 Codex와 같은 에이전트 프레임워크와 직접적으로 통합 가능합니다.

결론적으로 agent-file-lock은 커널 레벨의 불변성 플래그와 부모 디렉토리 보호 전략을 결합하여, 에이전트의 환경에서 의도치 않은 시스템 변경을 방지하는 강력하고 견고한 방어막을 제공합니다.