Skip to content

agent-setup.md

Latest commit

 

History

History
88 lines (73 loc) · 6.45 KB

agent-setup.md

File metadata and controls

88 lines (73 loc) · 6.45 KB
Raw

에이전트를 통한 설치와 권장 설정

이 문서는 사용자가 설치 또는 설정을 요청했을 때 수행하는 절차다. 목표는 ABC 영어 입력, 글가드 한글 입력, Karabiner의 Caps Lock 전환이다. 이미 승인된 작업은 반복해서 허락을 묻지 말고 가능한 단계까지 진행한다. 관리자 인증·권한 승인·로그아웃을 자동으로 완료했다고 가정하지 않는다.

1. 현재 상태와 백업

  • macOS 버전, 설치된 글가드 버전, 활성 입력 소스, Karabiner 설치·실행 여부를 확인한다.
  • /Library/Input Methods/GeulGuard.app와 ~/Library/Input Methods/GeulGuard.app의 중복 설치 여부를 확인한다. QA 이름의 앱도 확인하되 이름만으로 삭제하지 않는다.
  • ~/.config/karabiner/karabiner.json이 있으면 원본 그대로 날짜가 포함된 별도 백업을 만들고 경로를 기록한다. 선택된 프로필, Caps Lock 매핑, 키보드별 활성화 상태를 확인한다. 설정이 없으면 Karabiner 초기 설정부터 진행한다.
  • 입력 소스 목록과 ‘이전 입력 소스 선택’ 단축키를 기록한다.

2. 글가드 설치

  1. README의 공식 GitHub 최신 릴리스에서 GeulGuard.pkg를 받는다. 버전과 다운로드 출처를 기록하고 macOS 패키지 서명·Gatekeeper 검증 결과를 확인한다. 검증 실패를 보안 기능 비활성화로 우회하지 않는다.
  2. 기존 입력 중인 내용을 먼저 확정하고 ABC로 전환한다. 설치 프로그램으로 PKG를 설치한다. 관리자 암호가 필요하면 사용자가 시스템 인증창에 직접 입력하도록 한다. 채팅이나 스크립트 인자로 암호를 받지 않는다.
  3. 사용자가 작업을 저장한 뒤 로그아웃/로그인하도록 안내한다. 임의로 로그아웃하거나 앱을 강제 종료하지 않는다. 이후 시스템 설정 → 키보드 → 텍스트 입력 → 편집에서 ABC와 글가드 두벌식을 추가한다. 단순 파일 복사만으로 입력 소스 등록 완료를 선언하지 않는다.
  4. 설치된 버전과 실제 선택 가능한 글가드 두벌식을 확인한다.

업데이터가 포함된 배포본의 업데이트는 글가드 메뉴의 ‘업데이트 확인…’에서 진행할 수 있다. 입력 중인 글자를 확정하고 ABC로 전환한 뒤 설치를 진행한다. 관리자 인증·필요 시 로그아웃·설치 후 실제 입력 확인은 위와 동일하게 구분한다. 업데이트 기능이 비활성화된 개발 빌드는 공식 PKG 설치 경로를 사용한다.

소스 빌드를 명시적으로 요청한 경우에만 README의 개발 설치 경로를 사용한다. 개발 설치는 사용자 Library, PKG는 시스템 Library에 설치하므로 중복에 주의한다. 클린 설치를 요청한 경우 ABC 전환 후 기존 글가드 입력 소스를 제거하고, 확인된 글가드 번들만 백업/제거한 뒤 재설치한다. Input Methods 디렉터리 전체를 지우지 않는다.

3. 시스템 설정과 Karabiner

  1. ABC와 글가드 두벌식을 유지한다. 불필요한 소스를 정리하려면 사용자의 사용 여부를 확인한다. 기존 다른 언어 입력 소스를 임의로 삭제하지 않는다.
  2. ‘이전 입력 소스 선택’이 Control+Space인지 확인한다. 다른 단축키를 유지해야 하면 규칙의 출력 키를 실제 단축키에 맞춘다. 시스템 설정을 확인하지 않고 symbolic hotkey plist 전체를 덮어쓰지 않는다.
  3. Karabiner가 없으면 공식 사이트의 설치 파일을 사용한다. macOS가 요구하는 권한·드라이버 승인은 사용자에게 해당 화면을 안내한다. 기존 승인은 재요청하지 않는다.
  4. 규칙 JSON은 단일 규칙 객체다. Karabiner의 Complex Modifications → Add your own rule에 넣을 수 있다. 전체 karabiner.json 또는 assets용 rules 배열 포맷으로 착각하지 않는다.
  5. 기존에 같은 동작의 규칙이 있으면 재사용한다. 설명 문자열만으로 중복 여부를 판단하지 않는다. 충돌하는 Caps Lock 규칙이 있으면 영향을 설명하고 사용자의 의도에 맞춰 해결한다. 설정 파일을 직접 수정할 경우 선택된 프로필의 complex_modifications.rules에만 병합하고, 파싱 검증 후 원자적으로 저장한다. 다른 프로필·장치 설정·규칙을 보존한다.
  6. 규칙 활성화, 대상 키보드 활성화, 서비스 동작을 확인한다. 시스템의 기본 Caps Lock 전환 옵션에는 길게 누르는 대문자 고정 동작이 함께 있다. 이를 별도의 ‘길게 누르기 끄기’ 스위치로 안내하지 않는다. 이 규칙은 Karabiner가 Caps Lock을 처리하는 동안 전환 단축키로 바꾼다.

4. 검증과 결과 보고

실제 편집 가능한 빈 문서 또는 테스트용 세션에서 확인한다. 기존 터미널 명령줄에 테스트 문자열을 넣고 Enter를 눌러 실행하지 않는다.

  • ABC: 영문 연속 입력, 소문자 유지.
  • 글가드 두벌식: 안녕하세요, 읽어 앉아 없어 느낌 쓰, 연속 조합과 Backspace.
  • Caps Lock: 짧게 눌러 양방향 전환, 한글 조합 도중 전환, 길게 눌러도 대문자 고정이나 반복 전환이 발생하지 않는지 확인.
  • 앱: 가능한 Ghostty·Terminal·Warp와 Electron 편집기에서 각각 확인. SSH는 사용자가 지정한 대상에서 확인하며 로컬 조합 표시·커서와 원격 문자열을 구분한다. SSH에 UTF-8 문자열을 전송한 것만으로 IME 테스트 통과를 선언하지 않는다.

앱 조작 차단, 실제 키 입력 불가, 아직 필요한 로그아웃 등이 있으면 해당 항목을 미검증으로 남기고 이유를 적는다. 결과에는 설치 버전, 설정 변경, 백업 경로, 실제로 통과한 항목, 남은 사용자 조작을 기록한다. 기존 검증 범위는 호환성 기록을 참고한다.

복구

  • Karabiner에서 추가한 규칙만 비활성화/제거한다. 백업 이후 다른 수정이 없을 때만 전체 백업 복원을 사용한다. 단축키를 바꿨다면 기록한 이전 값으로 돌린다.
  • 글가드 제거는 ABC로 전환한 뒤 입력 소스 목록에서 제거하고 설치된 번들만 제거한다. 필요하면 작업 저장 후 로그아웃/로그인한다. 다른 입력기와 사용 중인 Karabiner 전체를 함께 제거하지 않는다.