AI OpenHands 사용법: 설정, 프롬프트, 실제 워크플로우 실용 가이드
유능한 개발자와 24시간 내내 페어 프로그래밍을 할 수 있기를 바란 적이 있다면 AI OpenHands가 놀라울 정도로 비슷합니다. AI OpenHands는 레포지토리를 읽고, 코드를 작성하고, 터미널을 실행하고, 문서를 탐색하고, 반복할 수 있는 오픈 소스 "AI 엔지니어"입니다. 마치 빠르게 배우고 지칠 줄 모르고 일하는 주니어 개발자와 같습니다. 그러나 올바르게 설정하고 조종하는 방법을 배우는 순간 그 힘이 발휘됩니다.
이 가이드는 AI OpenHands를 설치부터 고급 워크플로우까지 단계별로 사용하는 방법을 안내하여 자신감을 가지고 더 빠르게 출시할 수 있도록 도와줍니다.
- OpenHands를 로컬 또는 클라우드 모델로 실행
- 프롬프트, 레포지토리 및 작업에 대한 모범 사례
- 기능 작업, 디버깅, 테스트 및 문서에 대한 검증된 워크플로우
참고: OpenHands는 All Hands 팀과 커뮤니티에서 활발하게 개발 중입니다. 공식 문서는 현재 지침 및 팁을 위한 북극성입니다. 로컬 및 VM 설정을 문서화한 실무자의 실습 설치 가이드를 따를 수도 있습니다. 로컬 모델로 실행하는 경우 문서에 특정 지침도 포함되어 있습니다.
AI OpenHands란 무엇이며 왜 사용해야 할까요?
AI OpenHands를 키보드를 가진 AI 팀원이라고 생각하십시오. 채팅 전용 어시스턴트와 달리 OpenHands는 다음을 수행할 수 있습니다.
- 터미널을 사용하여 명령, 테스트 및 린터 실행
따라서 기능 구현, 버그 수정, 테스트 작성, 문서 생성, 리팩터링 및 코드베이스 현대화와 같은 작업에 이상적입니다. 프롬프트를 저글링하고 복사/붙여넣기하는 대신 OpenHands에 목표를 부여하고 사용자가 움직임을 감독하면서 반복하도록 할 수 있습니다.
빠른 시작: OpenHands를 사용하는 가장 빠른 방법
시작하는 방법에는 여러 가지가 있습니다. 선택은 클라우드 LLM을 사용할지 아니면 모든 것을 로컬에서 실행할지에 따라 다릅니다.
옵션 A: 클라우드 LLM 사용 (가장 쉬움)
- 공식 "빌드 시작" 및 "시작하기" 문서를 따라 앱을 설치하고 실행합니다. 일반적으로 다음을 수행합니다.
- 필수 구성 요소 설치 (경로에 따라 Docker, Node, Python, Git)
- 지원되는 클라우드 모델 (예: OpenAI, Anthropic 또는 프로젝트에서 지원하는 기타 모델)에 대한 API 키 제공
- OpenHands 인터페이스를 실행하고 리포지토리를 연결합니다.
이 방법을 사용하면 최소한의 컴퓨팅 오버헤드로 빠르게 생산성을 높일 수 있습니다.
옵션 B: 로컬 LLM으로 OpenHands 실행
- 코드를 클라우드에 보관하지 않거나 API 비용을 피하고 싶다면 공식 문서의 로컬 LLM 가이드를 사용하십시오.
- 호환되는 로컬 모델 설정 (당시 지원되는 Ollama 또는 기타 백엔드를 통해)
- 머신에 적절한 VRAM/CPU 및 디스크 공간이 있는지 확인
옵션 C: VM에 배포
- 전용 환경이 필요한 경우 실무자는 VM에서 OpenHands를 스핀업하고 몇 분 안에 앱을 빌드하는 방법을 문서화했습니다. 이는 안정적인 공유 AI 엔지니어 인스턴스를 원하는 팀에 유용합니다.
첫 번째 실행: 프로젝트 설정 및 작업 프레임
OpenHands는 코드를 볼 수 있을 때 빛을 발합니다. 다음으로 시작하십시오.
- OpenHands가 구조를 매핑할 수 있도록 프로젝트를 실행하거나 인덱싱합니다.
좋은 작업 프레임 예:
- "토큰 기반 이메일 링크를 사용하여
auth 서비스에 사용자 암호 재설정을 추가합니다. 기존 mailer 모듈을 사용합니다. 토큰 생성 및 만료에 대한 단위 테스트를 추가합니다. 사용자 데이터 스키마를 변경하지 마십시오."
이것이 작동하는 이유:
- 구성 요소, 범위, 종속성 및 경계를 지정합니다. 더 명확할수록 OpenHands가 더 잘 계획하고 실행합니다.
OpenHands에 효과적인 프롬프트를 작성하는 방법
프롬프트를 간결한 티켓이라고 생각하십시오. 가장 좋은 것은:
- 파일, 모듈 또는 테스트 참조: "
auth/routes.py 및 tests/test_auth.py 참조"
- 제약 조건 명시: "DB 스키마 변경 없음; 기존 인터페이스 유지"
- 수락 기준 포함: "테스트 통과해야 함:
pytest -k password_reset"
재사용할 수 있는 템플릿:
목표: <빌드하거나 수정할 내용>
컨텍스트: <관련 파일, 알려진 제약 조건, 외부 서비스>
수락: <통과하는 모습: 테스트, 엔드포인트, 메트릭>
경계: <변경하지 않거나 피해야 할 접근 방식>
도구: <실행할 수 있는 명령, 스크립트 또는 데이터 소스>
핵심 워크플로우: 계획 → 실행 → 확인 → 개선
OpenHands는 일반적으로 다단계 계획을 제안합니다. 안내 방법은 다음과 같습니다.
- 초기에 계획을 승인하거나 조정합니다. 먼저 테스트를 실행하여 기준 실패를 설정하도록 푸시합니다.
- 성공을 정의하기 위해 테스트를 만들거나 업데이트한 다음 코드를 구현하도록 요청합니다.
- 테스트 스위트와 린터를 자주 실행하도록 합니다.
- 정체되면 파일 이름, 스택 추적 또는 로그와 같은 컨텍스트를 더 추가합니다.
전문가 팁: 모놀리식 편집 대신 작은 PR 크기 변경을 권장합니다. 이렇게 하면 검토 가능성과 롤백에 도움이 됩니다.
복사할 수 있는 예제 워크플로우
1) 기능 구현
- 프롬프트: "
orders 페이지에 CSV 내보내기를 추가합니다. 서버 측 페이지 매김을 사용하고 text/csv를 통해 결과를 스트리밍합니다. OrdersTable.jsx에 내보내기 버튼을 추가하고 routes/orders.ts에 엔드포인트를 추가합니다. 페이지 매김 및 헤더에 대한 테스트를 포함합니다."
- 변경 사항을 감독하고 승인하고 녹색이 되면 병합합니다.
2) 실패하는 빌드 디버깅
- 프롬프트: "CI가 Node 20에서 실패합니다.
build.mjs에서 ESM/CJS 가져오기 오류를 수정합니다. 기존 롤업 플러그인을 유지합니다. CI를 통과하도록 구성 및 코드를 업데이트합니다."
- 로그를 제공하거나 CI 아티팩트에 대한 링크를 제공합니다.
- OpenHands에 로컬에서 복제 (
npm run build)하고 최소한의 차이점을 제안하도록 요청합니다.
3) 테스트 커버리지 및 강화
- 프롬프트: "
payments/service.py의 커버리지를 62%에서 85% 이상으로 늘립니다. retry_charge, refund, webhook_signature에 대한 단위 테스트를 추가합니다. 테스트에서 버그가 노출되지 않는 한 비즈니스 로직을 수정하지 마십시오."
- OpenHands가 테스트를 생성하고 실행하고 개선하도록 합니다.
4) 문서 및 개발자 경험
- 프롬프트: 이 레포지토리에 대한
CONTRIBUTING.md 및 DEVELOPMENT.md를 만듭니다. 환경 설정, 스크립트, 테스트 명령 및 PR 지침을 포함합니다.
안전 장치: OpenHands를 유용하고 안전하게 유지
- 디렉터리 범위: 다른 곳에서 실수로 편집하지 않도록 특정 레포지토리 또는 디렉터리를 가리킵니다.
- 파일 보호: 구성 파일 또는 중요한 인프라를 가능한 경우 읽기 전용으로 표시합니다.
- 명령 감사: 파괴적인 명령 (예:
rm -rf, 데이터베이스 재설정)에 대한 승인이 필요합니다.
- 비밀 위생: 프롬프트에 API 키를 붙여넣지 마십시오. 환경 변수 및 마스크된 로그를 사용하십시오.
- 네트워크 액세스: 브라우징이 활성화된 경우 샌드박스에 넣고 아웃바운드 호출을 기록합니다.
로컬 대 클라우드 모델: 자신에게 적합한 모델 선택
- 장점: 강력한 추론/코딩, 최소한의 설정, 빠른 반복
- 단점: 지속적인 비용, 데이터 거버넌스 고려 사항
- 장점: 개인 정보 보호, 제어, 비용 예측 가능성
- 단점: 하드웨어 요구 사항, 모델 품질이 다양함, 더 많은 튜닝 필요
모델 백엔드 및 메모리 제한을 구성하려면 공식 로컬 LLM 지침을 참조하십시오.
팀 플레이: 협업 흐름에서 OpenHands 사용
- 분기 우선 워크플로우: OpenHands가 기능 분기를 만들고 PR 검토를 위해 변경 사항을 푸시하도록 합니다.
- 커밋 위생: 명확한 메시지가 있는 원자적 커밋을 생성하고 문제 번호를 참조하도록 요청합니다.
- PR 템플릿: 검토자가 무엇이 변경되었는지, 왜 변경되었는지 알 수 있도록 PR 템플릿을 생성하고 적용합니다.
- 코드 소유자: CODEOWNERS와 결합하여 AI 생성 PR을 올바른 검토자에게 라우팅합니다.
일반적인 문제 해결
- 정체되거나 루프가 발생합니다: 범위를 좁힙니다. 다음 단계를 설명하도록 요청합니다. 실패하는 테스트를 제공합니다.
- 지저분한 차이점: 더 작고 스테이징된 계획을 요청합니다. 먼저 테스트한 다음 최소한의 코드 변경을 요청합니다.
- 잘못된 파일 편집: 정확한 경로를 지정하고 경계를 상기시킵니다.
- 로컬에서는 통과하지만 CI에서 실패합니다: CI 환경 세부 정보 및 로그를 공유합니다. 컨테이너로 복제하도록 합니다.
성능 팁 및 파워 무브
- 웜 스타트 컨텍스트: 먼저 주요 파일 (
README, package.json, 기본 서비스 파일)을 읽도록 요청합니다.
- 스크립트 제공:
make test 또는 npm run verify를 제공하여 빠르게 유효성을 검사할 수 있도록 합니다.
- 도메인 교육: 간단한 아키텍처 개요를 제공합니다. 논리 오류가 줄어드는 데 도움이 됩니다.
- 스타일 적용:
.eslintrc, .prettierrc, black/ruff 구성을 가리켜 올바르게 형식을 지정하도록 합니다.
- 체크포인트 사용: 각 마일스톤 후에 요약 및 다음 단계를 요청하여 추적을 유지합니다.
실제 시나리오: 버그 보고서에서 한 시간 안에 패치로
- 상황: 프로덕션 버그로 인해
orders API에서 잘못된 JSON 페이로드에 대해 처리되지 않은 500이 발생합니다.
- 프롬프트: "
orders POST에서 잘못된 JSON에 대해 500을 재현합니다. 스키마 유효성 검사를 추가하고 오류 세부 정보와 함께 400을 반환합니다. 잘못된 페이로드를 포함하도록 테스트를 업데이트합니다."
- API를 로컬에서 실행하고 오류를 재현합니다.
- 테스트를 업데이트하고 CI가 통과되었는지 확인합니다.
절약된 시간: OpenHands가 스캐폴딩을 처리하는 동안 영향 분석 및 롤아웃에 집중했습니다.
OpenHands를 강화하는 통합
- 테스트 러너: pytest, Jest, Vitest, JUnit
- 빌드 도구: Vite, Webpack, Rollup, Babel
- 패키지 관리자: npm, pnpm, yarn, pip/poetry
- 린터/포매터: ESLint, Prettier, black, ruff
- 컨테이너: CI와의 로컬 패리티를 위한 Docker Compose
이러한 도구를 표준화함으로써 OpenHands는 스택에 대해 더 안정적으로 추론하고 개발 루프를 더 많이 자동화할 수 있습니다.
참고: OpenHands와 함께 Sider.AI 사용
관련성 점수: 8/10. OpenHands를 AI 엔지니어로 사용하는 경우 사양, PR 설명 및 문서화를 위해 연구 및 초안 작성 코파일럿과 함께 사용하는 것이 좋습니다. Sider.AI는 기술 사양을 빠르게 작성하거나 RFC를 요약하거나 OpenHands 실행 로그를 깔끔한 변경 로그 및 릴리스 정보로 변환하는 데 도움이 될 수 있습니다. 이 조합은 컨텍스트 전환을 줄입니다. OpenHands는 코드 작업을 처리하고 Sider.AI는 결과를 깔끔한 사용자 대면 문서로 변환합니다.
보안, 개인 정보 보호 및 규정 준수 체크리스트
- 비밀을 env 변수에 보관합니다. 프롬프트에 키를 포함하지 마십시오.
- 주니어 개발자의 PR처럼 AI 생성 변경 사항을 검토합니다.
- 툴체인 버전을 고정합니다. 잠금 파일에서 실수로 업그레이드하지 마십시오.
- 클라우드 LLM을 사용하는 경우 데이터 보존 정책에 맞춥니다.
OpenHands를 사용하지 않을 경우
- 강력한 테스트 또는 사양 스캐폴딩이 없는 새로운 알고리즘 설계
- 강력한 검토 프로세스가 없는 고도로 규제된 코드베이스
OpenHands와 함께하는 첫 60분: 미니 플레이북
- 0–10분: 공식 빠른 시작을 사용하여 설치 및 실행
- 10–20분: 레포지토리를 연결합니다. 프로젝트 구조를 매핑하도록 요청합니다.
- 20–35분: 작고 테스트 가능한 목표를 정의합니다. 계획을 승인합니다.
- 35–50분: 구현 및 테스트 실행을 허용합니다. 필요에 따라 넛지합니다.
- 50–60분: 차이점을 검토하고 개선하고 기능 분기로 병합합니다.
주요 링크 및 다음 단계
- OpenHands에 대한 공식 "빌드 시작" 및 사용 설명서: 팁, 빠른 시작 및 모범 사례.
- 로컬 LLM 설정 가이드: 머신에서 OpenHands를 완전히 구성하고 실행합니다.
- VM에 대한 커뮤니티 기반 설치 연습: 실제 설치 단계 및 빠른 데모 프로젝트.
요점
- 명확한 수락 기준이 있는 티켓과 같은 작업 프레임.
- 반복을 작게 유지합니다. 일찍 그리고 자주 테스트합니다.
- 안전 장치를 사용하고 변경 사항을 검토합니다. 주니어 팀원처럼 취급합니다.
- 편의를 위해 클라우드를 선택하고 개인 정보 보호를 위해 로컬 모델을 선택합니다.
- 사양 및 릴리스 정보를 가속화하기 위해 문서화 도구 (예: Sider.AI)와 페어링합니다.
FAQ
Q1: AI OpenHands를 빠르게 설치하고 사용하려면 어떻게 해야 합니까?
공식 빠른 시작을 사용하여 필수 구성 요소를 설치하고 지원되는 LLM (클라우드 또는 로컬)을 연결하고 UI를 실행하여 리포지토리를 연결합니다. "빌드 시작" 문서에서는 설정 팁과 함께 단계별 지침을 제공합니다.
Q2: 클라우드 모델 대신 로컬 LLM으로 OpenHands를 실행할 수 있습니까?
예. 로컬 LLM 가이드에 따라 로컬 모델 백엔드를 구성하고 컨텍스트 설정을 조정합니다. 이는 개인 정보 보호에 민감한 프로젝트 또는 API 비용을 피하는 데 이상적입니다.
Q3: 코딩 작업을 위해 OpenHands를 프롬프트하는 가장 좋은 방법은 무엇입니까?
목표를 정의하고, 특정 파일을 참조하고, 경계를 설정하고, 수락 기준을 포함하여 간결한 티켓과 같은 프롬프트를 작성합니다. 진행 상황을 확인하기 위해 테스트를 만들거나 실행하도록 요청합니다.
Q4: AI OpenHands는 프로덕션 코드에서 사용하기에 안전한가요?
주니어 개발자처럼 취급합니다. 분기 보호, 코드 검토 및 CI를 사용하여 변경 사항의 유효성을 검사합니다. 명령에 대한 안전 장치를 추가하고 프롬프트에서 비밀을 유지합니다.
Q5: OpenHands는 기존 코드 어시스턴트와 어떻게 비교됩니까?
채팅 전용 도구와 달리 OpenHands는 레포지토리 내에서 명령을 실행하고, 파일을 편집하고, 자율적으로 반복할 수 있습니다. 기능, 디버깅 및 테스트와 같은 엔드 투 엔드 작업을 위해 구축되었습니다.
