aos — AI-powered Git Helper

aos는 git이 익숙하지 않은 팀원도 쉽게 쓸 수 있도록 만든 AI 기반 CLI 도구입니다. 브랜치 병합 중 충돌이 발생하면 AI가 양쪽 변경사항을 분석하여 둘 다 살리는 방향으로 자동 통합합니다.

---

목차

1. 설치
2. 최초 설정
3. Claude Code 연동
4. 팀 워크플로우 개요
5. 명령어 전체 목록
6. 시나리오별 사용법
7. 이메일 알림 설정
8. 설정 변경
9. AI 제공자
10. 새 버전 릴리스
11. 요구사항

---

설치

pip install aos-git

---

최초 설정

프로젝트 루트 디렉토리에서 1회 실행합니다.

aos setup

단계별 안내에 따라 아래 항목을 입력합니다.

항목	설명
AI 제공자	databricks 또는 anthropic
Databricks Host / Token	Databricks 사용 시 입력
Anthropic API Key	Anthropic 사용 시 입력
안내 메시지 언어	ko (한국어) 또는 en (영어)
이메일 알림	알림 받을 브랜치 + 수신자 이메일 목록 (선택)

설정값은 ~/.aos/config.toml에 저장됩니다. 알림 설정 시 프로젝트 루트에 scripts/notify_config.toml이 자동 생성됩니다.

git merge.conflictstyle=diff3 도 자동으로 전역 설정됩니다. AI가 BASE(공통 조상) 코드까지 참고하여 더 정확한 병합을 수행합니다.

---

Claude Code 연동

aos를 Claude Code와 연동하면 /aos 슬래시 커맨드로 skill을 호출하고, 충돌 발생 시 Claude가 자동으로 aos 사용을 권장받습니다.

1단계 — 전역 skill 설치 (pip install 후 1회)

aos install

• ~/.claude/skills/aos/SKILL.md 에 skill 파일 설치
• ~/.claude/CLAUDE.md 에 /aos 트리거 등록

2단계 — 프로젝트별 연동 (저장소 루트에서 1회)

aos claude install

• 프로젝트 CLAUDE.md 에 aos 사용 규칙 추가
• .claude/settings.json 에 PreToolUse 훅 등록
  → 충돌 파일이 감지되면 Claude에게 aos merge / aos pull 사용을 자동 안내

제거

aos claude uninstall   # 프로젝트 연동 제거
aos uninstall          # 전역 skill 제거

---

팀 워크플로우 개요

[병합 관리자]                       [팀원 A, B, C ...]
      │                                     │
  feature 브랜치에서 각자 작업              │
      │                                     │
  aos merge feature/xxx  ────────────────   │
  (충돌 시 AI 자동 해결 + 커밋)             │
      │                                     │
  aos push  (main 업데이트)                 │
      │                                     │
  pre-push hook 실행                        │
      │                                     │
  이메일 알림 발송 ──────────────→  aos sync 실행
                                    (최신 main 반영 + 충돌 시 AI 자동 해결)

---

명령어 전체 목록

aos setup

AI 및 알림 설정을 초기화합니다.

aos setup           # 전체 설정 (최초 1회 또는 AI 설정 변경 시)
aos setup --notify  # 알림 설정만 변경 (수신자 추가/제거, 브랜치 변경 등)

---

aos checkout

브랜치를 이동하거나 새로 만듭니다.

# 인수 없이 실행하면 화살표 키로 브랜치를 선택하는 인터랙티브 UI가 표시됩니다
aos checkout

# 브랜치명을 직접 지정할 수도 있습니다
aos checkout main               # 브랜치 이동 (없으면 원격에서 자동 가져옴)
aos checkout feature/my-work    # 원격 브랜치도 자동으로 로컬 생성 후 이동
aos checkout -b feature/new     # 새 브랜치 생성
aos checkout -b feature/new --push   # 새 브랜치 생성 + 원격에 즉시 push

인터랙티브 선택 화면 예시:

? 전환할 브랜치를 선택하세요
❯ * main  (현재)
    feature/data-pipeline
    feature/report-ui
    origin/feature/remote-only  (원격)

---

aos branch

브랜치 목록을 보기 좋게 출력합니다.

aos branch        # 로컬 브랜치 목록
aos branch -a     # 원격 브랜치 포함 전체 목록 (자동 fetch)
aos branch -d feature/xxx   # 브랜치 삭제

---

aos add

변경된 파일을 스테이징합니다.

aos add                  # 변경된 파일 전체 스테이징
aos add src/main.py      # 특정 파일만 스테이징
aos add src/ tests/      # 여러 경로 지정

---

aos commit

스테이징된 파일을 커밋합니다.

aos commit -m "feat: 기능 설명"

---

aos push

현재 브랜치를 원격에 push합니다.

aos push

---

aos pull

현재 브랜치에 원격 변경사항을 가져옵니다. 충돌 시 AI가 자동 해결합니다.

aos pull

---

aos status

현재 작업 상태를 보여줍니다.

aos status

---

aos merge

다른 브랜치를 현재 브랜치에 병합합니다. 충돌 발생 시 AI가 자동으로 해결하고 커밋까지 완료합니다.

aos merge feature/my-work           # 로컬 브랜치 병합
aos merge origin/feature/my-work    # 원격 브랜치 병합 (자동 fetch)
aos merge feature/my-work --no-fetch   # fetch 없이 바로 병합

충돌 해결 흐름:

충돌 감지
  └─→ AI가 BASE / OURS / THEIRS + 타임스탬프 분석
        └─→ 통합 결과 미리보기 출력
              └─→ [y] 적용  [N] 건너뜀  [e] 직접 편집
                    └─→ 모든 충돌 해결 완료 → 자동 커밋

---

aos sync

최신 main(또는 지정 브랜치)을 현재 브랜치에 반영합니다. 병합 관리자가 main을 업데이트한 후 팀원이 실행합니다. 충돌 발생 시 AI가 자동으로 해결하고 커밋까지 완료합니다.

aos sync              # origin/main → 현재 브랜치에 반영
aos sync --base dev   # origin/dev 기준으로 반영

---

시나리오별 사용법

A. 팀원 — 일상적인 작업

# 1. 작업 브랜치로 이동 (화살표로 선택하거나 이름 직접 입력)
aos checkout
# 또는
aos checkout feature/my-work

# 2. 파일 수정 후 저장
aos add
aos commit -m "feat: 기능 추가"
aos push

# 3. 병합 관리자로부터 이메일 알림 수신 후 → 최신 main 반영
aos sync
aos push

---

B. 팀원 — 새 작업 시작

# 최신 main 기준으로 새 브랜치 생성
aos checkout main
aos pull
aos checkout -b feature/new-feature --push

---

C. 병합 관리자 — main 업데이트

# 팀원 브랜치를 main에 병합
aos checkout main
aos merge feature/team-member-work
# 충돌이 있으면 AI가 자동 해결 후 커밋까지 완료

# main에 push → pre-push hook 실행 → 팀원에게 이메일 자동 발송
aos push

---

D. 원격 브랜치 목록 확인 후 이동

aos branch -a
# ┌────────────────────────────────────────┐
# │ *  main                                │
# │    feature/data-pipeline               │
# │    remotes/origin/feature/report-ui    │
# └────────────────────────────────────────┘

# 이름을 입력하거나 인터랙티브 UI로 선택
aos checkout feature/report-ui

---

이메일 알림 설정

aos setup 또는 aos setup --notify 실행 시 알림 설정을 완료하면 scripts/notify_config.toml이 자동 생성됩니다.

파일	역할
scripts/notify_config.toml	수신자 이메일 목록 저장
.git/hooks/pre-push	push 시 알림 스크립트 자동 실행 (symlink)

생성 후 한 번만 커밋하면 이후 자동 동작합니다.

git add scripts/notify_config.toml
aos commit -m "chore: add notify config"
aos push

알림 이메일 예시

제목: [aos-git] main 브랜치가 업데이트됐습니다 (a1b2c3d4)

main 브랜치에 새로운 변경사항이 병합됐습니다.
각자 브랜치에서 아래 명령어를 실행하여 최신 버전을 반영해주세요.

  aos sync
  aos push

──────────────────────────────
업데이트 정보
  작업자  : 이과장
  커밋    : a1b2c3d4 — merge: feature/data-pipeline
  프로젝트: https://gitlab.example.com/project
──────────────────────────────

---

설정 변경

AI 설정 전체 변경

aos setup

이전 설정값이 기본값으로 표시되므로 변경이 필요한 항목만 입력하고 나머지는 Enter로 유지할 수 있습니다.

알림 설정만 변경 (수신자 추가/제거, 브랜치 변경)

aos setup --notify

변경 후 커밋·push 하면 즉시 반영됩니다.

git add scripts/notify_config.toml
aos commit -m "chore: update notify recipients"
aos push

---

AI 제공자

Databricks Model Serving (기본)

사내 Databricks 환경을 사용합니다.

# ~/.aos/config.toml
[ai]
provider = "databricks"
model = "databricks-claude-sonnet-4-6"

[databricks]
host = "https://adb-xxxx.azuredatabricks.net"
token = "dapi..."

Anthropic API

[ai]
provider = "anthropic"
model = "claude-sonnet-4-6"

[anthropic]
api_key = "sk-ant-..."

---

새 버전 릴리스 (관리자용)

GitLab CI가 v* 형식의 태그를 감지하면 자동으로 PyPI에 배포합니다.

1회 사전 준비 — PyPI 토큰 등록

GitLab 프로젝트 → Settings → CI/CD → Variables 에서 추가:

Key	Value	Options
PYPI_API_TOKEN	PyPI에서 발급한 API 토큰 (pypi-...)	Masked 체크

배포 방법

# 스크립트 사용 (권장)
./scripts/release.sh 0.5.0
# pyproject.toml 버전 수정 → 커밋 → 태그 생성 → push 까지 자동 처리

push 후 GitLab CI/CD → Pipelines 에서 배포 진행 상황을 확인할 수 있습니다.

---

요구사항

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