AI 코딩을 작업 관리 및 코드 리뷰와 결합한 오픈 소스 개발자 도구입니다. Async는 Claude Code + Linear + GitHub PR을 하나의 주관이 뚜렷한 (opinionated) 워크플로우로 통합합니다.

Async가 하는 일

• 코딩 작업을 자동으로 조사 - 실행 전 코드베이스를 분석하고 명확한 확인을 위한 질문을 던집니다.
• 클라우드에서 코드 변경 사항 실행 - 로컬 설정을 건드리지 않고 격리된 환경에서 실행됩니다.
• 작업을 검토 가능한 하위 작업으로 분할 - 더 쉬운 코드 리뷰를 위해 스택 디프 (stack diffs)를 생성합니다.
• 전체 워크플로우 처리 - 앱을 떠나지 않고 GitHub 이슈부터 머지된 PR까지 처리합니다.

왜 Async인가?

전통적인 AI 코딩 도구들은 새로운 프로젝트에는 훌륭하게 작동하지만, 무언가를 망가뜨려서는 안 되는 성숙한 코드베이스에서는 어려움을 겪습니다. Async는 이러한 일반적인 문제들을 해결합니다:

• 사전 계획 강제 - 항상 명확한 질문을 던지며 실행 전 확인을 요구합니다.
• 컨텍스트 스위칭 (context switching) 제거 - 사용자가 다른 작업을 하는 동안 클라우드에서 비동기적으로 실행됩니다.
• 간편한 작업 추적 - GitHub 이슈를 자동으로 가져오며, PM 도구의 비대함을 방지합니다.
• 내장된 코드 리뷰 - 앱을 떠나지 않고 스택 디프 (stacked diffs)에 댓글을 달고 반복 작업을 수행할 수 있습니다.

작동 방식

1. 온보딩 및 작업 생성: Async GitHub App을 설치하고 저장소를 선택합니다. Async는 열려 있는 GitHub 이슈를 작업으로 자동 가져옵니다.

2. 조사 단계 (Research Phase): 새로운 작업은 Google Cloud Run (GCR) 작업을 트리거하여 저장소를 클론하고 조사 에이전트 (research agent)를 실행합니다. 에이전트는 코드베이스를 분석하고 명확한 확인을 위한 질문을 생성합니다. 작업은 자동으로 실행되거나 사용자의 입력을 기다립니다.

3. 실행: 또 다른 격리된 GCR 작업이 Claude Code를 사용하여 실행을 처리합니다. 기능 브랜치 (feature branch) 생성 → 작업을 하위 작업으로 분할 → 각 작업을 별도의 커밋으로 실행 → PR 오픈 단계를 거칩니다.

4. 코드 리뷰 (Code Review): 리뷰는 Async 내에서 이루어집니다. 각 하위 작업 (subtask)의 집중된 차이점 (diffs)을 단계별로 검토하고, 코멘트를 남기며, 수정을 요청 (새로운 하위 작업 생성)하거나 승인 (스쿼시 및 머지 (squash and merge))할 수 있습니다.

기술 스택 (Tech Stack)

• 백엔드 (Backend): 비동기 (async) 지원 기능이 포함된 FastAPI
• AI 모델 (AI Models): 구현을 위한 Claude Code, 리서치를 위한 OpenAI/Anthropic/Google 모델
• 클라우드 (Cloud): 컨테이너화된 실행 환경을 갖춘 Google Cloud Platform
• 데이터베이스 (Database): Firebase Firestore
• 통합 (Integrations): GitHub App, Stripe 결제, 이메일 알림
• 프론트엔드 (Frontend): 데스크톱 및 모바일 지원

설정 (Setup)

가상 환경 (virtual environment)을 생성하고 활성화합니다:

uv venv .venv
source .venv/bin/activate

환경을 명시적으로 동기화하려면 다음 명령어를 실행하세요:

uv sync

그 다음, pre-commit 린트 (lints)를 설정하기 위해 다음을 실행하세요:

pre-commit install

로컬 개발 (Local Development)

에이전트 (agent)를 로컬에서 실행하려면 루트 디렉토리에 .env 파일(예시로 .env.local 참고)을 생성하세요.

"async-firebase.json"이라는 이름의 Firebase 설정 파일을 생성하세요.

Google Cloud 클라이언트 라이브러리에 기본 로그인을 부여하려면 다음 명령어를 실행하세요:

gcloud auth application-default login

서버를 시작하려면:

uvicorn src.server:app --reload --port 8000

린트 (lint)를 수행하려면 다음 명령어를 실행하세요:

uv run ruff format .
uv run ruff check . --fix

테스트 (Testing)

모든 유닛 테스트 (unit tests)를 실행하려면:

python -m pytest

API 문서 (API Documentation)

FastAPI 서버는 다음과 같은 주요 엔드포인트 (endpoints)를 제공합니다:

인증 (Authentication)

• POST /auth/auth-with-github - 액세스 코드 (access code)를 통한 전체 GitHub OAuth 흐름
• POST /auth/verify-email - 이메일 인증 코드 전송
• POST /auth/redeem-email-code - 이메일 인증 코드 검증
• POST /auth/invite-people - 팀 초대장 전송
• POST /auth/redeem-invite-code - 초대 코드 검증

GitHub 통합 (GitHub Integration)

• POST /github/handle-github-events - GitHub 웹훅 (webhook) 이벤트 처리 (이슈, PR, 푸시)
• POST /github/submit-review - 승인 또는 수정 요청을 포함한 코드 리뷰 제출

Task Management (태스크 관리)

• POST /task/schedule-job - 태스크 실행 작업(연구, 실행, 수정, 인덱싱) 예약
• WebSocket /task/chat - AI 에이전트와의 실시간 태스크 통신

Onboarding (온보딩)

• POST /onboarding/onboard-github - GitHub App 설치 및 리포지토리 설정 완료

Payment (결제)

• POST /payment/create-checkout-session - 구독을 위한 Stripe 체크아웃 세션 생성
• POST /payment/create-portal-session - 고객 결제 포털 접속
• POST /payment/handle-stripe-events - Stripe 웹훅 (webhook) 이벤트 처리

Support (지원)

• POST /support/handle-contact-us - 문의 양식 제출 및 리드 (lead) 생성

Google Cloud Run Jobs

시스템은 태스크 처리를 위해 격리된 Google Cloud Run jobs를 사용합니다:

Job Types (작업 유형)

• execute-task - Claude Code를 사용한 주요 태스크 실행

  • 리포지토리를 기능 브랜치 (feature branch)로 클론 (clone)
  • Claude Code의 플랜 모드 (plan mode)를 사용하여 태스크를 하위 태스크로 분할
  • 각 하위 태스크를 별도의 커밋 (commit)으로 실행
  • 완료 시 풀 리퀘스트 (pull request) 생성

• research-task - 코드베이스 분석 및 요구사항 수집

  • 리포지토리 구조 및 컨텍스트 (context) 분석
  • 모호한 요구사항에 대해 명확히 하기 위한 질문 생성
  • 실행을 위한 구조화된 태스크 요약 생성

• revise-task - 코드 리뷰 피드백 처리

  • 리뷰 댓글 및 요청된 변경 사항 처리
  • 피드백을 해결하기 위한 새로운 하위 태스크 생성
  • 업데이트된 요구사항으로 재실행

• index-project - 리포지토리 인덱싱 및 설정

  • 프로젝트 구조 및 프로그래밍 언어 분석
  • 태스크 실행을 위한 프로젝트 메타데이터 설정
  • AI 에이전트 분석을 위한 리포지토리 준비

각 작업은 리포지토리가 클론되고 필요한 모든 의존성 (dependencies)이 설치된 격리된 환경에서 실행됩니다.

Deployment (배포)

Prerequisites (사전 요구 사항)

• Cloud Run이 활성화된 Google Cloud Platform 계정
• Firestore가 포함된 Firebase 프로젝트
• 조직을 위해 구성된 GitHub App
• 결제 처리를 위한 Stripe 계정

환경 변수 (Environment Variables)

프로덕션 환경에서 다음 항목들을 설정하십시오:

• ANTHROPIC_API_KEY - Claude API 접근
• OPENAI_API_KEY - OpenAI API 접근
• GOOGLE_API_KEY - Google AI API 접근
• STRIPE_SECRET_KEY - Stripe 결제 처리
• GITHUB_WEBHOOK_SECRET - GitHub 웹훅 (webhook) 검증
• DB_URI - 데이터베이스 연결 문자열 (connection string)

클라우드 배포 (Cloud Deployment)

이 애플리케이션은 자동 확장 (automatic scaling) 및 격리된 작업 실행 (isolated task execution) 기능을 갖춘 Google Cloud Run에서 실행되도록 설계되었습니다.

기여하기 (Contributing)

1. 저장소 (repository)를 포크 (Fork) 합니다.
2. 기능 브랜치 (feature branch)를 생성합니다 (git checkout -b feature/amazing-feature).
3. 변경 사항을 적용합니다.
4. 테스트 및 린팅 (linting)을 실행합니다.
5. 변경 사항을 커밋 (commit) 합니다 (git commit -m 'Add amazing feature').
6. 브랜치로 푸시 (push) 합니다 (git push origin feature/amazing-feature).
7. 풀 리퀘스트 (Pull Request)를 생성합니다.

작성하신 코드가 기존 스타일을 따르고 모든 테스트를 통과하는지 확인해 주세요.

라이선스 (License)

이 프로젝트는 MIT 라이선스 (MIT License) 하에 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

지원 (Support)

질문이나 문제가 있는 경우, GitHub 이슈 (issue)를 생성하거나 팀에 문의해 주세요.

자신의 코드베이스를 깊이 이해하고 있는 숙련된 개발자들을 위해 만들어졌습니다. Async는 위대한 무언가를 만들기 위해 당신이 필요로 할 마지막 도구입니다.