사용자 의도를 유지하며 직접 해결하고, 실제 결과까지 확인하는 OpenCode 하네스
무엇을 만들고 싶은지 알려주세요. 하네스는 프로젝트의 맥락을 찾아 작업하고, 코드뿐 아니라 실제 동작과 화면까지 확인하도록 돕습니다.
처음 사용하기 · 일하는 흐름 · 역할 · 스킬과 도구 · 설치 · 검증과 한계
Note
이 하네스는 OpenCode 위에서 동작합니다. 별도의 새 실행 엔진이나 자동 품질 판정기를 설치하는 방식이 아닙니다.
OpenCode에서 프로젝트를 열고 목표와 지켜야 할 것을 평소처럼 말하면 됩니다. 역할 이름이나 명령어를 외울 필요는 없습니다.
화면을 바꾸고 싶을 때
“이 대시보드를 현장 담당자가 다음 행동을 바로 알 수 있게 개선해줘. 기존 기능은 유지하고 모바일 화면도 확인해줘.”
기능을 만들고 싶을 때
“현장 자료를 비교하는 기능을 구현해줘. 기존 데이터를 보존하고 실제 동작과 오류 상태까지 확인해줘.”
먼저 살펴보기만 할 때
“현재 화면의 문제와 개선 방향을 분석해줘. 파일은 수정하지 마.”
Tip
목표 사용자, 유지할 기능, 접근하면 안 되는 데이터가 있다면 함께 알려주세요. 중요한 제약을 처음부터 전달할수록 작업 범위를 더 분명하게 잡을 수 있습니다.
요청하기 → 제품과 현재 상태 이해 → 설계·구현 → 실제 결과 확인 → 보고
| 순서 | 하는 일 |
|---|---|
| 이해 | 사용자 목표와 프로젝트 문서·코드·현재 변경을 살펴봅니다. |
| 판단 | 필요한 역할·스킬·도구를 고르고, 중요한 선택에는 이유를 설명합니다. |
| 구현 | 승인된 범위에서 만들고, 문제가 발견되면 고칩니다. |
| 확인 | 테스트와 실제 동작을 보고, 화면 작업은 실제 화면과 주요 상태도 확인합니다. |
| 보고 | 완료한 것, 확인한 것, 아직 확인하지 못한 것을 나눠 알려줍니다. |
이것은 대표적인 흐름이지 모든 작업에 강제되는 고정 절차는 아닙니다. 작은 수정은 간단히 처리하고, 큰 작업이나 불확실한 문제에는 필요한 만큼 더 살펴봅니다.
평소 요청은 그대로 사용합니다. 일반 요청도 구현·검증·필요한 수정까지 이어서 처리하며,
사용자가 역할이나 /goal을 관리할 필요는 없습니다. 별도 장기 실행이 필요할 때만 내장
/goal 목표와 /goal pause, /goal resume, /goal clear를 선택합니다.
KSI의 Lead Goal 자동 시작 계획과 상태 전달 연결은 제거했습니다.
목표는 세션별이어서 Build의 목표가 자식에 자동 상속되는 것은 아닙니다. 자식 위임의 완료 표시나 내장
목표 완료 표시는 검사 성공·제품 수용을 보장하지 않습니다. 반복·평가에는 시간과 비용이 들 수 있습니다.
내장 목표 안내. 중요한 불확실성은 주 담당자의 재검토와 선택형 Plan·독립 검토로 확인합니다.
Build가 맥락과 전체 결과를 책임지며 조사·설계·구현·복구·검증을 직접 수행합니다. 작업 크기나 파일 수 때문에 반드시 넘기지는 않습니다. 분리의 이득이 전달·통합 비용보다 클 때만 다른 역할을 사용합니다.
사용자 → Build → 직접 조사·구현·검증·수정 → 완료 또는 실제 차단 보고
└─ 필요할 때만 Lead / General / Explore / Plan
| 역할 | 맡는 일 | 기본 모델 |
|---|---|---|
| Build | 사용자 의도를 유지하며 직접 해결하고 최종 결과를 확인합니다. | 세션에서 선택 |
| Lead | 분리해서 맡기는 것이 유리한 기능·작업 흐름을 완수합니다. | 부모 세션의 모델·추론 수준 상속 |
| Plan | 복잡한 문제와 대안을 분석합니다. 구현을 승인하지는 않습니다. | Sol High |
| General | 범위가 정해진 구현·조사·테스트를 수행합니다. | 부모 세션의 모델·추론 수준 상속 |
| Explore | 코드와 자료를 찾아 읽고 분석합니다. | GPT-6 Luna Low |
Important
위임은 고정 순서가 아니며 직접 구현은 작은 수정에만 한정되지 않습니다. 핵심 판단을 위임하면서 다른 모델로 자동 전환하지 않습니다. 경량 모델은 좁은 검색 등 적합한 작업에 선택하며, 부모는 자식 결과를 통합하고 실제 남은 일을 확인합니다. 기본 모델은 저장소 설정 기준이며 세션·프로젝트 설정에 따라 달라질 수 있습니다.
역할이 누가 일하는지라면, 스킬과 도구는 어떻게 일하는지를 돕습니다.
| 구분 | 무엇을 하나요? | 예시 |
|---|---|---|
| 스킬 | 특정 작업에 필요한 방법과 주의점을 제공합니다. | 화면 디자인, 사용자 흐름, 버그 진단, 접근성 |
| 커맨드 | 필요한 스킬을 불러오도록 요청하는 선택형 바로가기입니다. | /ux-audit, /debug, /perf |
| 플러그인·도구 | 에이전트가 자료를 확인하고 검증할 수 있게 돕습니다. | 시각 작업 도구, 선택형 기능 목록 |
| 외부 연결 | 필요할 때 문서·디자인 참고자료·이전 작업을 찾아봅니다. | Context7, Mobbin, ai-memory |
상황에 맞게 고르는 스킬의 예
| 이런 일이 필요할 때 | 스킬 |
|---|---|
| 화면을 디자인하고 다듬기 | impeccable |
| 새로운 웹 디자인의 대안 탐색 | hallmark, design-taste-frontend 중 과업에 맞게 선택 |
| 사용자가 일을 끝내는 흐름 설계 | journey |
| 메뉴와 정보 구조 정리 | organize |
| 화면의 뼈대와 배치 구상 | wireframe |
| 키보드·화면 읽기 등 접근성 확인 | building-accessible-interfaces |
| 명시적인 코드 보안 감사와 근거 보고 | security-audit |
이 스킬들은 설치되어 있고 해당 작업과 권한에 맞을 때 선택합니다.
/ux-audit은 UX 점검과 접근성, /debug는 버그 진단,
/perf는 성능 조사 스킬을 사용하도록 안내합니다. 예를 들어
/ux-audit 설정 화면처럼 쓸 수 있습니다. 명령을 쓰지 않아도 담당자가
일반 요청에 맞는 스킬을 선택할 수 있습니다.
일부 명확한 화면 요청에는 설치된 디자인 스킬을 자동으로 연결합니다. 다만 모든 요청을 정확히 알아보거나, 모델이 필요한 스킬을 항상 선택한다고 보장하지는 않습니다. 외부 스킬은 이 저장소에 묶어 두지 않으며 별도 설치가 필요합니다. Impeccable·Hallmark·Taste를 항상 함께 실행하지 않습니다. 보안 스킬 설치도 OS 실행 격리나 상시 보안 에이전트를 추가하지 않습니다. 현재 설치 범위를 확인하세요.
제품 자료 확인 → 이미지 등록 → 원래 요청과 이미지 함께 검토 → 필요한 수정
| 도구 | 하는 일 |
|---|---|
visual_prepare |
해당 세션의 요청과 선택한 제품·디자인 자료를 묶습니다. |
visual_capture |
허용된 PNG 또는 실행 중인 로컬 에뮬레이터 이미지를 등록합니다. 외부 증거 경로는 별도 설정·권한이 필요합니다. |
visual_review |
같은 화면의 전후 이미지와 문제를 함께 보여줍니다. |
visual_review_single |
비교할 이전 화면이 없을 때 이미지 한 장과 맥락을 보여줍니다. |
담당자는 원래 문제와 실제 사용자 의견을 함께 살펴봅니다. 이미지의 출처는 호출자가 설명해야 하며, 도구가 화면의 품질이나 실제 빌드를 자동으로 증명하지는 않습니다. 독립 검토자에게도 이미지가 자동으로 전달되는 것은 아니므로 허용된 방법으로 따로 제공해야 합니다. 시각 도구 자세히 보기
프로젝트가 허용하는 직접 이미지 검토도 정상 경로입니다. 보조 도구의 준비·영수증 실패 때문에 전체 작업을 멈추거나 저장소로 이미지를 옮겨 경계를 우회하지 않습니다. 직접 검토를 도구 영수증으로 기록하거나 캡처 한 장을 실제 빌드·품질의 자동 증명으로 삼지 않습니다.
이 하네스 프로젝트에서 필요할 때만 기능 목록을 조회합니다. 기능 목록 플러그인과
find-skills는 전역 기본 구성에서 제외했습니다. 도구 등록은 실제 사용 성공이 아니며,
검증은 실제 명령 결과와 동작·화면으로 확인합니다. 세션 증거 요약과 별도 판단 모델 연결은 기본 운영에서 제외했습니다.
| 확인 | 질문 |
|---|---|
| 기능 | 실제로 동작하나요? 기존 기능과 데이터를 지켰나요? |
| 화면 | 사용자가 해야 할 일과 다음 행동을 찾고 사용할 수 있나요? |
| 예외 상황 | 빈 화면·로딩·오류에서도 필요한 행동과 복구 방법이 보이나요? |
| 사용 환경 | 대상 기기에서 읽고 조작할 수 있나요? 필요한 접근성은 확인했나요? |
Important
작동 확인과 사용자 수용은 다릅니다. 테스트 통과, 스크린샷, 다른 에이전트의 “완료” 보고만으로 제품이 좋아졌다고 단정하지 않습니다. 확인하지 못한 기기·상태·사용자 평가는 그대로 남깁니다.
| 어디에 있나요? | 무엇을 담나요? |
|---|---|
| 전역 하네스 | 일을 찾고, 맡기고, 확인하는 공통 방식 |
| 각 프로젝트 | 제품의 목적, 사용자 업무, 기능·안전 기준 |
| 현재 코드와 결과 | 실제 구현과 확인한 동작·화면·남은 문제 |
하네스를 설치해도 다른 프로젝트의 문서가 자동으로 만들어지거나 바뀌지는 않습니다. 기존 문서를 찾아 사용하며, 특정 파일 이름을 모든 프로젝트에 강제하지 않습니다. 자세한 내용은 프로젝트 지식과 상태를 참고하세요.
Build의 모델은 세션에서 고릅니다. 제품 방향을 깊이 판단할 때는 Sol High, 방향이 정해진 반복 개발에는 DeepSeek Flash Max를 선택하는 운영을 고려할 수 있습니다. 사용 가능한 모델과 비용·데이터 정책은 각 환경에서 확인해야 합니다.
어느 모델이 항상 더 낫다는 결론은 아직 없습니다. 모델 시험과 한계
이미 승인된 개발은 테스트·화면 확인·발견된 결함 수정까지 진행합니다. 일부 외부 조건이 막혀도 독립적인 작업은 계속하고, 실제로 필요한 결정만 묻습니다. 사용자의 중단·범위 변경은 즉시 반영합니다. 목표·채택/거부한 방향·완료 조건·남은 일은 세션과 기존 정본에 연결하며 새 필수 문서 체계를 만들지 않습니다.
병행 변경을 발견하면 겹치는 범위부터 확인합니다. 필요한 경우 별도 작업본과 테스트 환경에서 진행하되, 미커밋 변경이 자동 상속되거나 DB·화면까지 격리된다고 가정하지 않습니다. 분리 작업 안내 · 실제 과업 평가 기준
ai-memory를 연결하면 이전 결정·실패·남은 작업을 다시 찾는 데 도움을 받을 수 있습니다.
별도 설치가 필요한 선택 기능이며, 기억보다 현재 사용자 요청과 프로젝트의 실제 상태가 우선합니다.
이 환경의 수집 범위, 개인정보 주의점과 설치 방법은 ai-memory 안내를 확인하세요.
이 저장소를 내려받는 것만으로 전역 설정이 바뀌지는 않습니다. OpenCode V2에서 사용하려면 기존 설정을 확인한 뒤 필요한 항목을 적용합니다.
- 기존 OpenCode 설정을 백업하고, 같은 이름의 사용자 설정이 있는지 확인합니다.
global/의 필요한 하네스 항목을 전역 설정에 수동으로 합칩니다.- 시각 어댑터와 필요한 선택형 도구를 각각의 설치기로 적용합니다.
- 설치 파일이 맞는지와 실행 중에 도구가 보이는지를 따로 확인합니다.
Caution
opencode.jsonc를 통째로 덮어쓰면 개인 설정이나 연결 정보가 사라질 수 있습니다.
정확한 백업·병합·확인·되돌리기 방법은 **설치 안내**를 따르세요.
어떤 파일이 들어 있나요?
| 위치 | 내용 |
|---|---|
global/AGENTS.md |
공통으로 따를 작업 원칙 |
global/opencode.jsonc |
역할·모델·권한과 선택 연결 설정 |
global/agents/lead.md |
Lead 역할 안내 |
global/commands/ |
선택해서 쓸 수 있는 명령 |
global/plugins/ |
시각 작업과 선택형 기능 목록 |
experiments/ |
자동 로딩·기본 설치에서 제외한 실험 코드 |
scripts/ · docs/ · tests/ |
설치·사용 안내와 검증 자료 |
global/은 저장소의 원본이고, ~/.config/opencode/는 전역 설치 위치입니다.
외부 스킬은 저장소에 포함되지 않으므로 필요한 스킬은 별도로 설치합니다.
공유할 때는 하네스 소스·설치기·문서·합성 테스트 자료를 골라 포함합니다.
개인 설정, 토큰, 로컬 모델과 이 저장소의 루트 AGENTS.md·.harness-journal/은
로컬 자료이며 공유 대상이 아닙니다.
작업 폴더에 다른 변경이 섞여 있을 수 있으므로 git add -A로 한꺼번에 묶지 말고
파일별로 확인하세요. .gitignore는 암호화나 비밀 탐지 기능이 아닙니다.
| 지킬 것 | 의미 |
|---|---|
| 승인된 범위 | 운영 환경·공유 서비스·자격증명은 허가 없이 변경하지 않습니다. |
| 기존 작업 | 다른 세션의 변경과 프로젝트 데이터는 보존합니다. |
| 분석 전용 | 살펴봐 달라는 요청을 구현 허가로 해석하지 않습니다. |
| 민감한 자료 | 토큰·개인정보를 저장소나 시각 자료에 넣지 않습니다. |
| 외부 연결과 비용 | 모델·외부 도구·유료 서비스는 해당 환경의 권한과 비용을 확인합니다. |
엄격하게 파일 변경을 막아야 한다면 말로 요청하는 것에 더해 OpenCode 세션에서 편집·셸 등 필요한 권한을 제한해야 합니다. 자식 에이전트의 권한과 자료 접근도 따로 확인합니다.
2026-11-02 운영 정리: 직접 완수·필요한 위임·실제 검증을 중심에 두고, KSI Lead Goal 연결·Decision 보조·세션 증거 요약은 기본 운영에서 제외했습니다. 최신 시험 결과와 설치·활성 범위는 검증 문서 한 곳에서 관리합니다.
Warning
이 검사는 도구 연결과 경계를 확인하는 자료입니다. 실제 제품의 디자인 품질, 사용자 만족이나 어느 모델이 더 나은지를 증명하지 않습니다.
검사 결과·실패·명령과 아직 확인하지 못한 범위는 검증과 한계에 정리했습니다.
| 더 알고 싶다면 | 문서 |
|---|---|
| 안전하게 설치하고 되돌리기 | 설치 안내 |
| 화면 자료와 이미지를 연결하는 방법 | 시각 작업 도구 |
| 프로젝트 문서와 상태를 관리하는 방법 | 프로젝트 지식과 상태 |
| 검사 결과와 남은 한계 | 검증과 한계 |
| 이전 작업 기억 연결 | ai-memory |
| 기능 목록·오프라인 진단 | 진단 안내 |
전체 문서와 과거 기록은 문서 안내에서 볼 수 있습니다.
MIT — Copyright (c) 2026 KSI