기타 코딩 에이전트 팁 및 스크립트
AI 코딩 에이전트, 터미널 사용자 정의(customization), 개발 도구에 대한 실용적인 가이드입니다. 각 가이드는 일상 업무 중 발생한 실제 문제, 이를 해결한 솔루션, 그리고 설정을 재현할 수 있는 복사-붙여넣기 설정들을 문서화합니다.
빠른 참고 자료 (Quick Reference)
| 가이드 | 해결된 문제 | 설정 시간 |
|---|
| 파괴적 Git 명령어 보호 | AI 에이전트가 git checkout --를 실행하여 커밋되지 않은 작업물을 파괴함 | 5분 |
| ... | | |
AI 에이전트 안전성 (AI Agent Safety)
파괴적 Git 명령어 보호 (Destructive Git Command Protection)
기원 이야기: 한 AI 에이전트가 병렬 코딩 세션에서 몇 시간 동안 작업한 커밋되지 않은 파일들에 대해 git checkout --를 실행했습니다. 해당 파일들은 git fsck --lost-found를 통해 복구되었지만, 이 사건을 계기로 기계적인 강제 시스템(mechanical enforcement system)을 구축하게 되었습니다.
Bash 명령어를 가로채고 파괴적인 작업을 실행하기 전에 차단하는 Claude Code용 Python 훅입니다.
차단된 명령어:
| 명령어 | 위험한 이유 |
|---|
git checkout -- <files> | 커밋되지 않은 변경 사항을 영구적으로 폐기함 |
| ... | |
작동 방식: Claude Code의 PreToolUse 훅 시스템은 각 Bash 명령어 실행 전에 가드 스크립트(guard script)를 실행합니다. 이 스크립트는 알려진 파괴적인 명령어를 패턴 매칭하고, 설명과 함께 거부 결정(deny decision)을 반환합니다. 안전한 변형들(예: git checkout -b, git clean -n, rm -rf /tmp/...)은 허용 목록(allowlisted)에 포함됩니다. | |
<details>
<summary><strong >빠른 설치 (Quick install)</strong></summary>
자동화된 설치 프로그램은 전체 가이드를 참조하세요. 실행 후:
작동 테스트:
echo '{"tool_name": "Bash", "tool_input": {"command": "git checkout -- file.txt"}}' | \
python3 .claude/hooks/git_safety_guard.py
</details>
전체 가이드 →
Post-Compact AGENTS.md 리마인더
문제점: 긴 코딩 세션 동안 Claude Code는 컨텍스트 제한 내에 머무르기 위해 대화 내용을 압축(compact)합니다. 압축 후, Claude는 AGENTS.md에 문서화된 프로젝트별 규칙을 '잊어버립니다'.
컨텍스트 압축을 감지하고 Claude에게 AGENTS.md를 다시 읽도록 상기시키는 bash 훅(hook)입니다.
작동 방식: Claude Code의 SessionStart 훅은 압축 후 source: "compact"와 함께 작동합니다. 이 훅은 해당 필드를 확인하여 Claude가 즉시 볼 수 있는 리마인더 메시지를 출력합니다.
<details>
<summary><strong >간편 설치</strong></summary>
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/misc_coding_agent_tips_and_scripts/main/install-post-compact-reminder.sh | bash
또는 수동으로 ~/.local/bin/claude-post-compact-reminder 파일을 생성합니다:
#!/usr/bin/env bash
set -e
INPUT=$(cat)
...
그리고 ~/.claude/settings.json에 추가합니다:
{
"hooks": {
"SessionStart": [
...
</details>
전체 가이드 →
터미널 커스터마이징
원격 머신을 위한 Ghostty Terminfo
Ghostty를 사용하여 원격 서버에 SSH로 접속할 때, 숫자 패드에서 Enter 키를 누르면 [57414u와 같은 쓰레기 데이터(garbage)가 표시될 수 있습니다. 이는 원격 시스템이 Ghostty가 사용하는 Kitty 키보드 프로토콜을 이해하지 못하기 때문에 발생합니다.
한 줄 수정 방법:
infocmp -x xterm-ghostty | ssh user@your-server 'mkdir -p ~/.terminfo && tic -x -o ~/.terminfo -'
<details>
<summary><strong >여러 서버를 위한 헬퍼 함수</strong></summary>
~/.zshrc에 추가합니다:
ghostty_push_terminfo() {
local host="$1"
[[ -z "$host" ]] && { echo "Usage: ghostty_push_terminfo <호스트>" >&2; return 1; }
...
그 후 실행합니다: ghostty_push_terminfo ubuntu@dev-server
</details>
전체 가이드 →
호스트 인식 컬러 테마(Host-Aware Color Themes)
여러 서버에 대해 터미널을 열어 놓았을 때, 각 연결에 색상 코드를 지정하면 실수로 잘못된 장치에서 명령을 실행하는 것을 방지할 수 있습니다.
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ PURPLE │ │ AMBER │ │ CRIMSON │
│ dev-server │ │ staging │ │ production │
...
두 가지 접근 방식:
| Ghostty/Shell | WezTerm/Lua |
|---|
| 설정 시간 | ~5분 | ~15분 |
| ... | | |
<details>
<summary><strong >Ghostty 빠른 설정</strong></summary>
~/.zshrc에 추가:
my-server() {
printf '\e]11;#1a0d1a\a\e]10;#e8d4f8\a\e]12;#bb9af7\a'
ssh [email protected] "$@"
...
printf 명령어는 터미널 색상을 변경하는 OSC(Operating System Command) 이스케이프 시퀀스를 전송합니다. ]11;#1a0d1a는 배경을 설정하고, ]111은 이를 초기화합니다.
</details>
전체 가이드 →
WezTerm 영구 원격 세션 (WezTerm Persistent Remote Sessions)
Mac 절전 모드, 재부팅 또는 전원 손실에도 살아남는 원격 터미널 세션입니다. 시스템d를 통해 원격 서버에서 실행되는 WezTerm의 네이티브 멀티플렉싱(multiplexing)과 wezterm-mux-server를 사용합니다.
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Local │ │ Dev │ │ Staging │ │ Workstation│
│ [3 tabs] │ │ [3 tabs] │ │ [3 tabs] │ │ [3 tabs] │
...
주요 기능:
| 기능 | 작동 방식 |
|---|
| 영구 세션 | 원격의 wezterm-mux-server가 상태를 유지하고, Mac은 단순히 재연결합니다. |
| ... | |
<details>
<summary><strong >원격 설정 (서버별)</strong></summary>
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/wezterm-mux-server.service << 'EOF'
...
</details>
전체 가이드 →
Agent Swarm을 위한 WezTerm Mux 튜닝
20개 이상의 AI 코딩 에이전트(Claude, Codex)를 동시에 실행할 때, 기본 wezterm-mux-server 설정으로는 감당하기 어렵습니다. 출력 버퍼가 오버플로우되고, 캐시가 불안정해지며(thrash), 연결 시간이 초과되어 모든 에이전트 세션이 종료됩니다.
본 가이드는 메모리를 처리량(throughput)과 교환하는 RAM 계층형 성능 프로필을 제공합니다:
| 설정 | 기본값 | 512GB 프로필 | 도움이 되는 이유 |
|---|
scrollback_lines | 3,500 | 10,000,000 | 에이전트는 방대한 출력을 생성합니다. 잘라내지 마십시오 |
| ... | | | |
스마트 크기 조정: 고정된 계층형 설정이 아닌 실제 RAM을 기반으로 선형 보간(linear interpolation)을 사용합니다. 200GB 시스템의 경우 비례적으로 조정된 설정을 받게 됩니다.
보너스: mux 서버가 응답하지 않을 때 reptyr를 사용하여 에이전트 세션을 tmux로 마이그레이션하는 긴급 복구 절차(세션의 약 50-70% 저장).
<details>
<summary><strong >빠른 설치 방법</strong ></summary>
./wezterm-mux-tune.sh
./wezterm-mux-tune.sh --dry-run
./wezterm-mux-tune.sh --ram 200
...
그런 다음 mux 서버를 재시작합니다:
pkill -9 -f wezterm-mux
wezterm-mux-server --daemonize
</details>
전체 가이드 → | 설치 스크립트 →
MX Master 썸휠(Thumbwheel) 탭 전환 기능
Logitech MX Master 마우스의 수평 썸휠은 대부분의 개발자가 거의 사용하지 않는 수평 스크롤링을 위해 설계되었습니다. 이 가이드는 이를 터미널, 에디터, 브라우저 간의 탭 전환 용도로 재활용합니다.
설정 방법:
- BetterMouse를 설치합니다($10 일회성).
- 썸휠을
Ctrl+Shift+Arrow에 매핑합니다:
Thumbwheel << → Ctrl+Shift+Left
Thumbwheel >> → Ctrl+Shift+Right
- 각 애플리케이션(WezTerm, Ghostty, VS Code 등)에 키 바인딩을 추가합니다.
컴패니언 스크립트(Companion script): bettermouse_config.py는 백업 또는 공유를 위해 BetterMouse 설정을 JSON으로 내보내고 가져옵니다. 현재 설정을 보려면 uv run bettermouse_config.py show로 실행하세요.
<details>
<summary><strong >왜 Ctrl+Shift+Arrow인가요?</strong></summary>
| 단축키 | 문제점 |
|---|
Ctrl+Tab | Chrome에서 재할당 불가 |
| ... | |
</details>
전체 가이드 →
Ghostty용 Doodlestein Punk 테마
깊은 우주 검정 배경에 전기 네온 악센트가 특징인 활기찬 사이버펑크에서 영감을 받은 색 구성표입니다.
┌─────────────────────────────────────────────────────┐
│ 배경: #0a0e14 (deep space black) │
│ 전경: #b3f4ff (electric cyan) │
...
빠른 설치:
mkdir -p ~/.config/ghostty/themes
cp doodlestein-punk-theme-for-ghostty ~/.config/ghostty/themes/
사용법: Ghostty 설정(~/.config/ghostty/config)에 추가하세요:
theme = doodlestein-punk-theme-for-ghostty
<details>
<summary><strong >전체 팔레트</strong></summary>
| 인덱스 | 일반(Normal) | 밝음(Bright) | 색상 이름 |
|---|
| 0/8 | #1a1f29 | #3d4f5f | Black/Gray |
| ... | | | |
</details>
테마 파일 →
Zellij 스크롤 휠 수정
문제점: 터미널 멀티플렉서로 Zellij를 실행하는 원격 Linux 머신에 SSH 접속할 경우, 마우스 스크롤 휠이 터미널 버퍼를 스크롤하는 대신 화살표 키 신호를 보냅니다. 만약 셸 히스토리를 위해 atuin을 사용한다면, 스크롤 할 때마다 위쪽 화살표가 전체 화면 히스토리 TUI(Text User Interface)를 열게 됩니다.
이것은 known Zellij limitation으로 알려진 문제점입니다. Zellij는 적절한 마우스 스크롤 이벤트를 받지만, 이를 화살표 키 입력으로 변환합니다. 해결 방법(workaround)은 macOS에서 Hammerspoon을 사용하여 스크롤 휠 이벤트를 가로채고 이를 Alt+Up/Alt+Down 키 스트로크로 변환하는 것입니다. Zellij는 이 입력을 스크롤 명령어로 처리합니다.
Scroll wheel → Hammerspoon (macOS) → Alt+Up/Down → SSH → Zellij → ScrollUp/ScrollDown
세 가지 구성 요소:
| 구성 요소 | 위치 | 기능 |
|---|
| Zellij keybinds | 원격 서버 | Alt+Up/Alt+Down → 잠금 모드(locked mode)에서 ScrollUp/ScrollDown으로 변환 |
| ... | | |
<details>
<summary><strong id="quick-zellij-config">간단한 Zellij 설정</strong></summary>
keybinds clear-defaults=true {
locked {
bind "Ctrl g" { SwitchToMode "Normal"; }
...
</details>
<details>
<summary><strong id="hammerspoon-gotchas">Hammerspoon 주의사항</strong></summary>
이벤트 탭(event tap)을 조용히 망가뜨릴 수 있는 세 가지 사항:
local 변수는 Lua에 의해 가비지 컬렉션되어 30~90분 후에 탭을 종료시킵니다. 전역(global) 변수를 사용하세요.- 콜백 내부에서
:post() 또는 keyStroke()를 호출하면 너무 느려집니다. 대신 이벤트를 테이블(table) (두 번째 반환 값)로 반환하세요.
- **macOS의
tapDisabledByTimeout**은 느린 탭을 종료시킵니다. 5초마다 다시 활성화하는 **워치독 타이머(watchdog timer)**를 추가하세요.
</details>
이 가이드에서는 또한 WezTerm의 기본 mouse_bindings가 이 용도로 신뢰할 수 없는 이유와 스무스 스크롤링 마우스로 스크롤 감도를 조정하는 방법도 다룹니다.
전체 가이드 →
원격 개발 (Remote Development)
macOS NFS 자동 마운트 (macOS NFS Auto-Mount)
원격 Linux 워크스테이션에 프로젝트가 /data/projects 경로로 있는 경우, 부팅 시 Mac에서 이를 자동으로 마운트하고 우아한 재시도 로직을 적용할 수 있습니다.
얻게 되는 것:
~/dev-projects → /Volumes/dev-server/projects → 10.0.0.50:/data/projects
구성 요소:
구성 요소 및 목적
| 구성 요소 | 목적 |
|---|
| Mount script | 서버가 오프라인일 때 지수 백오프(exponential backoff)를 사용하여 재시도합니다. |
| ... | |
<details>
<summary><strong style="font-weight: bold;">빠른 설정</strong></summary>
sudo tee /usr/local/bin/mount-dev-nfs << 'EOF'
...
</details>
전체 가이드 →
예산형 10GbE 직접 연결 (Budget 10GbE Direct Link)
Mac을 Linux 워크스테이션에 10GbE로 직접 연결하여 약 $90의 비용으로 800+ MB/s 전송 속도를 달성할 수 있습니다.
Mac Mini M4 Linux Workstation
┌─────────────┐ ┌─────────────────┐
│ Thunderbolt │◄──Cat6 $5────►│ Built-in 10GbE │
...
필요한 구성 요소:
| 구성 요소 | 비용 |
|---|
| IOCREST Thunderbolt 10GbE 어댑터 | ~$85 (AliExpress) |
| Cat6 케이블 | ~$5 |
많은 고급 워크스테이션(Threadripper PRO, EPYC)에는 사용하지 않는 10GbE 포트가 있습니다. IOCREST 어댑터는 Mac Studio의 내장 10GbE와 동일한 Aquantia 칩을 사용합니다.
추가 기능:
- 속도 보고서가 포함된 SHA-256 검증 파일 전송
- Mac과 Linux 간 클립보드 동기화 (Wayland/X11)
- 원격 디스플레이 웨이크업 명령어
- AI 코딩 에이전트 별칭 (Claude, Gemini, Codex)
전체 가이드 →
범용 코딩 에이전트 하네스 업데이트기 (Universal Coding Agent Harness Updater)