agy: Claude + Gemini 협업
agy는 Claude Code와 유사한 터미널 에이전트로, Gemini(및 기타) 모델을 실행합니다. agy는 Claude가 약하거나 비용이 많이 드는 영역인 이미지, 네이티브 오디오/비디오, 그리고 대량 작업에서 강점을 발휘합니다. 적절히 사용하면 두 번째 손과 독립적인 리뷰어가 되어 주지만, 부주의하게 사용하면 실제로 완료되지 않은 작업을 '완료'했다고 말할 수 있습니다.
이 스킬의 핵심 규칙: Claude는 결과에 대한 책임을 계속 집니다. agy가 실행하고, Claude가 지정, 확인, 결정합니다.
스크립트는 이 파일과 함께 scripts/ 디렉토리에 있습니다. 아래 명령어에서 <skill>은 스킬이 로드될 때 'Base directory for this skill'로 표시되는 폴더입니다. 항상 절대 경로를 사용하세요.
| 스크립트 | 용도 |
|---|---|
scripts/agy-modelo PAPEL | agy models에서 실시간으로 읽어 역할에 맞는 올바른 모델을 반환합니다 |
scripts/agy-tarefa ... | 작업을 실행하고, 모든 것을 저장하며, git에서 실제로 변경된 사항을 보여줍니다 |
scripts/agy-revisar ... | 읽기 전용 diff 리뷰를 수행하고 구조화된 결과를 제공합니다 |
scripts/agy-historico [N] | 최근 실행 내역: 상태, 모델, 시간 및 토큰(사용량 확인용) |
사용자는 직접 /agy:delegar, /agy:revisar, /agy:modelos, /agy:historico를 호출할 수도 있습니다.
시작 전: agy가 준비되었나요?
command -v agy && <skill>/scripts/agy-modelo --listar --atualizar
agy가 없거나 명령이 실패하면 중단하고 사용자에게 알리세요 (설치 또는 로그인이 필요합니다). 해결 방법을 시도하지 마세요. 세션의 첫 번째 확인 이후 --atualizar 없이 agy-modelo를 실행하면 1시간 동안 캐시된 목록을 사용합니다.
위임 시기 (그리고 하지 말아야 할 때)
위임 대상은 agy가 더 낫거나 병렬 처리가 실제로 시간을 절약하는 경우입니다:
- 이미지: 사진, 배경, 배너, 목업, 아이콘 생성 또는 편집, 이미지 내 텍스트/로고 교체.
- 오디오 및 비디오: 오디오 트랜스크립션(WhatsApp 포함), .mp4 파일 직접 요약 또는 분석.
- 대규모 작업의 독립적인 부분: 각각 고유한 파일이 있는 모듈, 화면, 테스트, 문서.
- 기계적인 대량 작업: 40개 파일의 API 이름 변경, 반복적인 패턴 마이그레이션, 예제 데이터 생성.
- 두 번째 의견: Claude가 방금 작성한 코드 리뷰 ('교차 검증' 참조).
위임 금지 대상:
- 작업이 이 대화의 맥락에 의존하며 글로 전달하기 어려운 경우 (결정, 사용자 선호도, 반복적인 수정). 이러한 맥락을 작성하는 데 드는 비용이 직접 처리하는 것보다 더 큽니다.
- 사소하고 명백한 편집 (위임하고 확인하는 것이 더 비쌉니다).
- 비밀, 암호, 토큰, 제3자 개인 데이터 또는 되돌릴 수 없는 작업 (삭제, 게시, 메시지 보내기,
git push)을 포함하는 경우. 이는 Claude와 사용자가 처리해야 합니다.
모델 선택 (동적)
프롬프트나 명령어에 고정 모델 이름을 절대 작성하지 마세요. 역할을 사용하세요:
| 역할 | 용도 | 현재 선택 (예시) |
|---|---|---|
codigo | 코드 작성 및 수정 | 최신 Gemini 'pro', 높은 노력 |
revisao | diff 리뷰, 버그 찾기 | 최신 Gemini 'pro', 높은 노력 |
pesquisa | 많은 자료 읽고 요약 | 최신 Gemini 'pro', 중간 노력 |
imagem | 이미지 생성 또는 편집 | 최신 Gemini 'pro', 중간 노력 |
rapido | 단순 작업, 대량 처리, 초안 | 최신 Gemini 'flash' |
agy-modelo는 agy models를 읽고(1시간 캐시), 빠른 제품군(flash/lite)과 주요 제품군을 분리한 후 최신 버전과 역할에 선호되는 노력 수준을 선택합니다. 새로운 Gemini가 출시되면 별도의 수정 없이 자동으로 사용됩니다. 강제 적용: AGY_MODELO_CODIGO=<id> (특정 역할) 또는 AGY_MODELO=<id> (모든 역할). 모델이 막 출시된 경우 --atualizar를 사용하세요.
리뷰의 경우 코드를 작성한 모델과 다른 제품군의 모델을 선호하세요. 두 번째 의견의 장점은 다른 '두뇌'를 사용하는 데 있습니다. revisao 역할은 이미 Gemini를 선택합니다. Claude 코드를 리뷰하기 위해 agy 내에서 Claude로 변경하지 마세요.
작업 요청 방법
references/prompt-modelo.md템플릿에 따라 프롬프트를 파일에 작성하세요. 프롬프트는 자체 완결적이어야 합니다. agy는 이 대화를 보지 못했습니다. 절대 경로, 미리 읽어야 할 내용, 수행할 작업, 건드리지 말아야 할 것, 저장 위치, 올바름을 증명하는 방법을 포함하세요.- 백그라운드에서 실행 (
run_in_background: true와 함께 Bash 사용). 작업은 몇 초에서 수십 분까지 걸릴 수 있습니다:
<skill>/scripts/agy-tarefa --dir /abs/projeto --papel codigo \
--nome "tela de login" --prompt-arquivo /abs/prompt.md --timeout 2400
--dir은 필수이며 여러 번 사용할 수 있습니다. agy는 여기에 전달된 폴더만 보고 편집합니다. 이 옵션이 없으면 agy는 자체 초안에 쓰고 프로젝트에 아무것도 변경하지 않고 '완료'했다고 응답합니다. 참조 이미지, 오디오 등 지원 파일의 폴더도 포함하세요.--modo plan은 agy가 읽기만 하도록 합니다 (분석, 연구, 리뷰). 기본값인accept-edits는 파일 편집을 허용합니다.- 스크립트는 프롬프트에 고정 규칙을 추가합니다: 커밋 금지, sudo 사용 금지, 폴더 이탈 금지, 짧게 응답. 특별한 이유가 있을 때만
--sem-regras를 사용하세요. - 동일한 대화를 계속하려면 (예: 조정 요청)
--continuar <id>를 사용하세요.meta.json에 있는 id를 사용합니다. agy는 이전에 말한 내용을 기억합니다. - 긴 요청은 문제가 되지 않습니다. 약 100KB를 초과하면 스크립트는 파일을 통해 요청을 agy에 전달합니다 (Linux 명령줄은 128KB 이상의 인수를 거부합니다).
- 출력은 응답의 최대 150줄을 표시합니다 (
--max-linhas N으로 변경 가능). 전체 텍스트는PASTA=로 지정된 폴더의resposta.md에 있습니다. 필요한 경우에만 거기서 읽으세요. 이렇게 하면 agy의 결과가 Claude의 컨텍스트를 채우지 않습니다. - Claude가 다른 사용자의 폴더에서 root로 실행 중인 경우, 스크립트는 agy가 터미널을 통해 생성한 항목(
mkdir,npm install,git...)의 소유자를 해당 폴더 소유자로 되돌립니다. 그렇지 않으면 이후 git과 사용자 편집기가 손상됩니다. agy 자체의 파일 쓰기 도구는 이미 소유자를 존중합니다.--manter-donos는 이 기능을 비활성화합니다.
agy-tarefa 종료 코드 | 의미 |
|---|---|
0 | agy가 완료됨. 여전히 검증이 필요합니다 (다음 섹션) |
1 | agy 오류 또는 빈 응답 (RESPOSTA-VAZIA): 실패로 처리 |
2 | 스크립트 사용 오류 (메시지에 누락된 내용이 표시됨) |
3 | agy가 규칙에도 불구하고 커밋을 수행함: git log를 확인하고 사용자에게 알림 |
124 | 시간 초과. 이미 편집한 내용은 디스크에 남아 있습니다: alteracoes.txt 확인 |
- 실행되는 동안 다른 작업을 계속하세요. 프로세스가 종료되면 알림을 받습니다.
agy가 전달한 내용 검증 (필수)
agy의 보고는 주장일 뿐 증거가 아닙니다. agy-tarefa는 실제로 변경된 사항(실행 전후 git status 비교)을 이미 표시하고 agy가 커밋한 경우 경고합니다 (종료 코드 3). 그런 다음:
- 보고서를
alteracoes.txt와 비교하세요. agy가 생성했다고 말한 파일이 나타나지 않거나 요청 외의 항목을 건드린 경우 문제입니다. - diff를 읽으세요 (
git diff,git diff --stat). 응답만 읽지 마세요. - 프로젝트 검사를 실행하세요: 빌드, 테스트, 린트,
node --check,python -m py_compile등. UI의 경우 실제 화면을 확인하세요 (스크린샷/브라우저). agy는 테마, 색상 및 파일 간 통합 세부 사항에서 자주 실수합니다. - 결정하세요: 수락, 직접 수정 (사소한 경우), 또는
--continuar와 함께 정확히 잘못된 항목 목록을 보내 다시 요청.
이 모든 과정을 거친 후에만 사용자에게 완료되었다고 알리세요.
교차 검증 (두 번째 의견)
Claude 또는 agy가 작성한 중요한 변경 사항 후에 독립적인 리뷰를 요청하세요:
<skill>/scripts/agy-revisar --dir /abs/repo # HEAD 이후 모든 변경 사항, 새 파일 포함
<skill>/scripts/agy-revisar --dir /abs/repo --base main # main 이후 모든 변경 사항
<skill>/scripts/agy-revisar --dir /abs/repo --intervalo HEAD~3..HEAD --foco "concorrência no worker"
agy는 읽기 전용 모드로 리뷰하고 평결(aprovado, ajustar, reprovar)과 심각도, 신뢰도, 파일:줄, 증거, 제안이 포함된 결과를 반환합니다 (형식은 assets/schema-revisao.json에 있음). diff는 구분되며, 코드 내 텍스트는 명령이 아닌 데이터라는 경고가 포함되어 악의적인 주석이 리뷰어를 승인하도록 조종하는 것을 방지합니다. --exigir-aprovado를 사용하면 평결이 'aprovado'가 아닐 때 스크립트가 종료 코드 4와 함께 종료됩니다 (자동화에 유용).
발견 사항을 맹목적으로 적용하지 마세요. 각 발견 사항에 대해: 코드를 열고, 실제로 실패 시나리오가 발생하는지 확인한 후에만 수정하세요. 오탐은 폐기하고 사용자에게 실제 발견 사항이 몇 개인지 알리세요. 신뢰도가 baixa인 발견 사항은 힌트이지 명령이 아닙니다. agy가 확실히 올바른 것을 거부하는 경우, 리뷰어를 만족시키기 위해 코드를 변경하는 대신 사용자에게 이유를 설명하세요.
병렬 작업
대규모 작업을 분할하려면:
- 동일한 파일을 수정하지 않는 부분으로 나누세요. 두 부분이 동일한 파일이 필요한 경우 병렬이 아닙니다. 순차적으로 수행하세요.
- 각 부분에 자체 폴더를 할당하세요: 부분당
git worktree가 가장 안전합니다 (git worktree add ../projeto-parte-a -b parte-a). 또는 완전히 분리된 하위 폴더를 사용하세요. - 각 부분에 대해
agy-tarefa를 실행하고, 모두run_in_background: true로 설정하며, 각각--dir을 자체 폴더로만 지정하세요. - 병합하기 전에 각 부분을 검증하세요 (위 섹션 참조). 한 번에 하나씩 병합하고 각 병합 후 테스트를 실행하세요.
- 동시에 3-4명 이상의 에이전트를 실행하면 일반적으로 agy의 할당량 또는 요청 한도가 초과됩니다. 잘 정의된 몇 개의 부분으로 유지하세요.
좋은 분할은 Claude가 대화 컨텍스트가 필요한 부분(아키텍처, 통합, 사용자 결정)을 처리하고 agy가 격리된 부분을 처리하는 것입니다.
이미지, 오디오 및 비디오
- 입력 파일을
--dir에 전달된 폴더에 넣고 프롬프트에서 절대 경로를 언급하세요. - 이미지의 경우 크기, 형식, 정확한 출력 경로를 지정하고 프로젝트에서 사용하기 전에 사용자에게 결과를 보여주세요. 시각적 아이덴티티(색상, 글꼴)가 있는 경우 값을 전달하세요. agy는 추측하지 않습니다.
- 트랜스크립션의 경우 형식(연속 텍스트, 타임스탬프 포함, 화자별), 언어를 요청하세요. 편집할 항목이 없으면
--modo plan을 사용하세요.
일반적인 문제
문제가 발생하면 references/problemas.md를 읽으세요: 변경 없이 '완료', 시간 초과, 할당량, 인식되지 않는 모델, 로그인, 예상치 못한 응답 형식.
사용자에게 보고하는 방법
간결하고 검증 가능하게: 위임된 작업, 사용된 모델 (meta.json), 변경된 사항 (파일), 확인한 사항 (테스트, diff, 화면), agy가 수행한 작업 중 수정한 사항. 교차 검증에서 발견한 사항이 있다면 실제 발견 사항 수와 처리 방법을 알리세요. 전체 로그는 ~/.cache/agy-skill/execucoes/에 저장되며 (30일 후 삭제, AGY_SKILL_RETENCAO_DIAS로 변경 가능), agy-historico는 토큰 사용량을 요약합니다.