aos — AI-powered Git Helper

git을 몰라도, AI가 충돌을 해결해주는 Git 도우미입니다.

pip install aos-git
aos init          # 프로젝트 초기화 (최초 1회)
aos setup         # AI + 알림 설정 (최초 1회)

⚠ 메일 알림이 안 오나요? → aos doctor 한 번이면 무엇이 잘못됐는지 보입니다. "전역 설정이 없습니다 / SMTP 비밀번호가 비어있습니다 / 수신자가 없습니다" 처럼 정확한 사유와 해결 명령어를 알려줍니다.

🔥 자주 쓰는 명령어 (이것만 알면 됩니다)

프로젝트 처음 설정할 때 (최초 1회)

aos init          # git hooks + 알림 수신자/관리자 설정

매일 하는 작업

aos checkout -b feature/내브랜치   # 새 브랜치 만들기
# ... 코드 수정 ...
aos add                           # 변경사항 스테이징
aos commit -m "작업 내용"          # 커밋
aos push                          # 원격에 반영

상대방 변경사항 받기

aos pull          # 충돌 있으면 AI가 자동 해결
# 또는
aos sync          # 최신 main을 내 브랜치에 반영 (AI 해결)

브랜치 병합

aos merge feature/팀원작업         # 브랜치 병합 (충돌 시 AI 해결)
aos push                           # 병합된 main을 원격에 반영

새 버전 릴리스

aos release patch                  # 0.8.5 → 0.8.6 (자동 PyPI 배포)

상태 확인

aos status        # 지금 뭐가 바뀌었는지
aos log           # 커밋 히스토리 보기
aos branch        # 브랜치 목록

📦 설치

pip install aos-git

최초 설정

aos init           # git hooks + 알림 설정 (프로젝트 1회)
aos setup          # AI + SMTP + PyPI 토큰 (최초 1회)

aos init은 프로젝트마다 1번, aos setup은 내 PC에서 1번만 하면 됩니다.

🆙 업데이트 (이미 사용 중인 사람)

pip install --upgrade aos-git
aos doctor           # 환경이 정상인지 한 번에 확인

업데이트 후 메일 알림이 동작하지 않으면 99%는 SMTP 비밀번호 문제입니다. 전역 설정(~/.aos/config.toml)에만 저장되기 때문에 새 PC / 재설치 시 다시 입력해야 합니다.

업데이트 후 꼭 해야 할 것

aos init --hooks-only    # 새 pre-push hook 으로 갈아끼우기
aos setup --notify       # SMTP 비밀번호 재입력 (선택이지만 권장)

🩺 환경 점검 (문제 있을 때 첫 단계)

aos doctor               # 한 방에 진단
aos doctor --send-test   # SMTP 실제 테스트 메일까지 발송

각 항목이 Status / Check / Detail 컬럼으로 ✓/✗ 표시되고, ✗ 항목마다 정확한 해결 명령어가 안내됩니다.

자주 나오는 ✗ 와 해결

🚀 처음 사용하는 사람 (5분 셋업)

1. 설치: pip install aos-git
2. 프로젝트 초기화 (clone 받은 프로젝트 폴더 안에서):

   aos init
   

   • 메일 수신자(recipients)와 관리자(mergers) 이메일을 물어봅니다 — 팀원 본인과 관리자 이메일을 입력하세요.
3. 개인 PC 설정:

   aos setup
   

   • 역할 선택: 일반 팀원은 "👥 Member", 관리자는 "👑 Admin"
   • AI 제공자: 회사 정책에 따라 databricks 또는 anthropic
   • SMTP 발신 계정 / 비밀번호 입력 (Gmail은 앱 비밀번호 필요)
   • 설정이 끝나면 SMTP 실제 연결 테스트가 자동 실행됩니다 — 실패하면 사유가 표시되고 재입력 가능
4. 확인:

   aos doctor          # 모든 항목이 ✓ 인지 확인
   

5. 테스트 push: 아무 브랜치에 push 하면 hook 이 실행되고 [pre-push] 출력이 그대로 화면에 보입니다.

💡 SMTP 비밀번호는 각자 본인 PC에만 저장됩니다 (~/.aos/config.toml). 프로젝트에는 host/port/sender/tls/username만 저장되므로, 다른 팀원이 비밀번호를 볼 수 없습니다.

📋 전체 명령어

📖 상세 가이드

aos init — 프로젝트 초기화 (신규)

aos init                              # 전체 초기화
aos init --hooks-only                 # git hooks만 다시 설치

• git hooks 자동 설정 (clone 후 1회 실행)
• 팀원(recipients)과 병합 관리자(mergers) 이메일 등록
• 언제든 다시 실행 가능

aos setup — AI + 알림 설정

aos setup                             # 전체 설정 (AI + 알림 + 토큰)
aos setup --notify                    # 알림만 다시 설정
aos setup --pypi                      # PyPI 토큰만 등록

• AI 제공자: Anthropic / OpenAI / Ollama / Databricks / Custom
• 알림 채널: Email / Slack / Teams

aos checkout — 브랜치 이동

aos checkout                          # 화살표 키로 선택
aos checkout main                     # 브랜치명 직접 입력
aos checkout -b feature/내작업        # 새 브랜치 생성
aos checkout -b feature/x --push      # 생성 + 원격에 바로 push

aos merge — 브랜치 병합 (핵심 기능)

aos merge feature/팀원작업            # 충돌 시 AI가 자동 해결
aos merge origin/feature/x            # 원격 브랜치 병합
aos merge feature/x --no-fetch        # fetch 없이 바로 병합

aos resolve — 남은 충돌 이어서 해결

aos merge / pull / sync 도중 Ctrl+C로 중단됐거나, 수동으로 충돌이 발생했을 때 실행합니다. <<<<<<< 마커가 남은 블록만 골라 AI로 다시 해결하므로, 부분적으로 해결된 상태에서도 안전하게 이어갈 수 있습니다.

aos resolve               # 남아 있는 충돌 마커를 AI로 해결
aos resolve --auto        # 프롬프트 없이 전부 자동 적용

모두 해결되면 안내에 따라 aos add + aos commit 으로 마무리하면 됩니다.

aos sync — 최신 변경사항 반영

aos sync                              # origin/main → 내 브랜치
aos sync --base dev                   # origin/dev 기준

aos release — 버전 릴리스

aos release patch                     # 0.8.5 → 0.8.6 (추천)
aos release minor                     # 0.8.6 → 0.9.0
aos release major                     # 0.9.0 → 1.0.0
aos release 1.0.0                     # 원하는 버전 직접 지정
aos release --dry-run                 # 미리보기 (실제 실행 안 함)

자동 실행: 버전업 → 커밋 → 태그 → push → PyPI 배포

aos config — 설정 관리

aos config                            # 현재 설정 보기
aos config --test                     # AI + 알림 연결 테스트
aos config --edit                     # 설정 마법사 재실행
aos config pypi --token pypi-...      # PyPI 토큰 등록
aos config pypi --remove              # PyPI 토큰 삭제
aos config notify --add-recipient 이메일  # 수신자 추가

aos doctor — 환경 진단 (메일 안 올 때 첫 단계)

aos doctor                  # 한 방에 환경/설정 점검 + 해결 명령어 안내
aos doctor --send-test      # SMTP 실제 테스트 메일까지 발송

• git 저장소 여부, pre-push hook 설치/실행권한, ~/.aos/config.toml, AI/SMTP/수신자 상태, 실제 SMTP 연결을 한 화면에 ✓/✗로 보여줍니다.
• ✗ 항목마다 "어떤 명령으로 고치는지"가 즉시 표시됩니다.

🔄 팀 워크플로우

팀원

# 1. 작업 시작
aos checkout -b feature/데이터정제

# 2. 코드 수정 후 저장
aos add
aos commit -m "데이터 정제 로직 추가"
aos push

# 3. 알림 받으면 최신 버전 반영
aos sync
aos push

병합 관리자

# 1. 팀원 작업을 main에 병합
aos checkout main
aos merge feature/팀원작업       # 충돌 시 AI 해결

# 2. main 반영 (팀원에게 자동 알림)
aos push

# 3. 새 버전 릴리스
aos release patch

⚙️ 동작 방식

Pre-push Hook

push 시 자동 실행:

• main push → 팀원 이메일 알림
• feature/* push → 병합 관리자 알림
• v*.*.* 태그 push → 자동 PyPI 배포

PyPI 토큰 찾는 순서:

1. 환경변수 PYPI_API_TOKEN
2. ~/.aos/config.toml (aos setup --pypi)
3. ~/.pypirc

충돌 해결 흐름

충돌 감지 → AI 분석 (BASE/OURS/THEIRS) → 해결안 제안
  → [y] 적용 [N] 건너뜀 [e] 직접 편집 → 자동 커밋

☁️ Claude Code 연동

aos install          # 전역 skill 설치 (1회)
aos claude install   # 프로젝트 연동 (저장소마다 1회)

요구사항

• Python 3.11+
• git
• Anthropic API 키 또는 Databricks 접근 권한