zihoAutoResearch

기존 ML 프로젝트의 실험 근거·결과·판단을 로컬에 기록하고, 다음 세션에서 이어가는 가벼운 CLI와 에이전트 스킬입니다.

전처리, 모델, 손실 함수, 최적화 방법을 바꿀 때 “왜 시도했는지, 어떤 조건에서 비교했는지, 무엇을 채택했는지”를 함께 남깁니다. 데이터나 학습 환경을 새 플랫폼으로 옮길 필요 없이 기존 프로젝트에서 사용합니다.

PyPI · GitHub 릴리스 · 변경 내역 · 문제 제보

어떤 도구인가요?

• CLI (zar): 실험 계획·관측·비교·판단을 JSON으로 저장하고 형식·참조·근거 파일을 검사합니다.
• 에이전트 스킬: 사용 중인 코딩 에이전트가 프로젝트를 읽고, 허용된 범위 안에서 연구 절차를 따르도록 안내합니다.
• 재개와 보고서: 미완료 실험, 실패 기억, 후보 근거, 실험 계보를 조회하고 Markdown 보고서를 만듭니다.

CLI 자체는 LLM을 호출하거나 학습·코드 복구·대회 제출을 실행하지 않습니다. 실행은 사용자 또는 기존 에이전트가 담당하고, CLI에는 실제로 확인한 결과를 기록합니다. check 통과도 데이터 누수나 모델 품질의 자동 판정을 뜻하지 않습니다.

zar는 zihoAutoResearch의 약칭이자 실행 명령어입니다. 설치할 패키지 이름은 ziho-autoresearch이고, 설치 후에는 zar init, zar status처럼 사용합니다.

1. 설치

Python 3.11 이상이 필요합니다. 런타임 외부 라이브러리 의존성은 없습니다. Git 연결 기능을 사용할 때만 Git 실행 파일이 필요합니다.

uv가 있다면:

uv tool install ziho-autoresearch
zar --help

아래 버전 고정 예시는 v0.3.0 기준입니다. 현재 공개 상태는 릴리스 목록을 확인하세요.

zar를 찾지 못하면 uv tool update-shell을 실행하고 터미널을 다시 여세요. 버전 고정은 uv tool install 'ziho-autoresearch==0.3.0', 업데이트는 uv tool upgrade ziho-autoresearch로 합니다. 고정 버전이나 URL 설치의 업데이트 방법은 uv 안내를 참고하세요.

uv 없이 설치하려면:

python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows PowerShell에서는 위 줄 대신:
# .venv\Scripts\Activate.ps1
python -m pip install ziho-autoresearch
zar --help

2. 기존 프로젝트 연결

아래 ./my-ml-project를 이미 존재하는 ML 프로젝트 폴더로 바꾸세요. Windows에서도 경로에 공백이 있으면 따옴표로 감싸면 됩니다.

zar init --project ./my-ml-project
zar status --project ./my-ml-project --json

프로젝트 안에 .autoresearch/가 생성됩니다. 기존 코드·루트 program.md·AGENTS.md는 보존합니다. --project를 생략하면 현재 폴더를 사용하며 상위 폴더를 자동 탐색하지 않습니다.

처음에는 ready:false가 정상입니다. 목표, 비교 지표, 데이터·코드 식별자, 실행 환경, 명령, 예산, 수정 허용 경로를 채워야 합니다. 다음 단계의 에이전트에 설정을 도와달라고 하거나 처음 사용 안내를 따라 직접 작성하세요.

3. 에이전트에서 스킬 사용

Codex / Claude Code에 바로 설치

v0.3.0부터 지원합니다. 설치 방법과 전체 절차는 에이전트 설치 안내를 참고하세요. CLI가 설치된 뒤 사용할 에이전트 하나를 선택합니다.

# Codex: 지정한 ML 프로젝트에만 설치
zar skill install --agent codex --project ./my-ml-project

# Claude Code를 사용하는 경우
zar skill install --agent claude --project ./my-ml-project

필요한 스킬 폴더를 만들고 번들 전체를 복사합니다. 기존 스킬은 덮어쓰지 않습니다. 대상 프로젝트를 에이전트에서 연 뒤, Codex에서는 $ziho-autoresearch, Claude Code에서는 /ziho-autoresearch를 선택하고 다음처럼 요청하세요.

이 프로젝트를 학습 실행 없이 점검하고 첫 실험 계획을 제안해줘.

목록에 나타나지 않으면 에이전트를 재시작하고 스킬 설정을 확인하세요. 에이전트의 실행 환경에서도 zar --help가 실행되어야 합니다. 발견 경로에 설치하므로 기본 사용에 AGENTS.md 수동 연결은 필수가 아닙니다. 설치가 학습 실행을 승인하거나 실제 인식을 검증하지는 않습니다.

다른 에이전트에서 수동 연결

ML 프로젝트 밖의 편한 작업 폴더에서 실행하세요. --dest는 새로 만들 스킬 폴더이며 상위 폴더는 이미 있어야 합니다.

zar skill install --dest ./ziho-autoresearch-skill-0.3.0 --json

wheel에 포함된 SKILL.md와 references/ 전체를 추출합니다. 기존 폴더를 덮어쓰거나 에이전트에 자동 등록하지 않습니다. 출력된 절대 경로를 사용 중인 코딩 에이전트에 전달하세요.

<출력된 스킬 폴더>/SKILL.md를 읽고 <ML 프로젝트 절대 경로>를 점검해줘. 우선 실행 없이 현재 코드·데이터·평가 방법과 누락된 설정을 정리하고, 첫 실험 계획을 제안해줘.

실험 실행까지 맡길 때는 목표, 허용 변경 경로, 실행 환경, 횟수·시간 한도도 지정하세요. 비밀 키나 원본 개인정보를 대화 또는 실험 근거에 붙여넣지 마세요. 스킬을 업데이트할 때는 새 폴더로 추출해 사용자 수정과 비교합니다.

프로젝트의 AGENTS.md에 연결하기

수동 연결을 유지하거나 프로젝트별 적용 조건을 명시하려면 실험 대상 프로젝트의 AGENTS.md에 스킬의 SKILL.md 경로와 적용 조건을 추가하세요. 기존 규칙은 유지하고, 스킬 전문이나 수시로 바뀌는 실험 상태를 복사하지 않습니다. 에이전트가 해당 지침 파일을 읽도록 설정되어 있는지는 사용하는 도구에서 확인하세요.

아래 연결 문구 생성 명령은 v0.3.0부터 지원합니다.

zar skill guidance --skill-dir ./ziho-autoresearch-skill-0.3.0

이 명령은 기존 스킬의 위치를 넣은 연결 문구를 화면에 출력합니다. 내용을 검토하고 대상 프로젝트의 기존 AGENTS.md에 필요한 부분만 병합하세요. 파일 생성·덮어쓰기·에이전트 자동 등록은 수행하지 않습니다. > AGENTS.md로 리디렉션하면 셸이 기존 파일을 지울 수 있으므로 사용하지 마세요. 공개 버전에서도 수동 연결 예시를 사용할 수 있습니다.

4. 기록 확인과 재개

zar status --project ./my-ml-project --json
zar context --project ./my-ml-project --max-bytes 16384 --json
zar check --project ./my-ml-project --json

• status: 설정 누락, 현재 선택, 미완료 실험과 예산 확인.
• context: 새 세션에 전달할 제한된 크기의 맥락 조회. 근거 파일의 존재·해시는 검사하지 않습니다.
• check: 기록과 근거 검사. 종료 코드뿐 아니라 경고 내용도 읽으세요. 초기 설정이 미완성이면 종료 코드 3이 나올 수 있습니다.

중단 후에는 에이전트에게 이렇게 요청할 수 있습니다.

같은 스킬과 프로젝트를 읽고 context와 status로 현재 상태를 확인해줘. unknown 실험은 실제 로그·프로세스 상태를 확인하기 전 재실행하지 말고, 새 근거로 상태를 정리해줘.

기록상 채택과 실제 작업 폴더의 코드는 별개입니다. keep 판단이나 선택 변경이 코드를 되돌리지 않습니다. 정확한 중단·재개 절차는 처음 사용·재개 안내를 참고하세요.

직접 기록할 때의 순서

JSON 입력을 직접 작성하거나 에이전트가 작성한 초안을 검토할 수 있습니다. CLI 레시피에 입력 예제가 있고, 파일 계약에 필수 필드와 상태 전이가 정리돼 있습니다.

위 명령에도 --project <프로젝트 경로>를 붙일 수 있습니다. 자세한 인자는 zar <명령> --help로 확인하세요. JSON 입력은 원본과 다른 파일에 작성합니다. .autoresearch/drafts/를 쓴다면 먼저 직접 생성해야 합니다.

학습 없이 체험하기

예제는 wheel에 포함되지 않습니다. 소스 배포본을 풀거나 이 저장소를 내려받고, CLI가 설치된 Python 환경에서 소스 폴더를 기준으로 실행하세요.

python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows PowerShell에서는 위 줄 대신:
# .venv\Scripts\Activate.ps1
python -m pip install ziho-autoresearch
python examples/mock-cycle.py --output ./demo-cycle

demo-cycle은 존재하지 않는 새 경로여야 합니다. 예제는 가짜 점수와 로그로 기록 → 비교 → 판단 → 보고서 흐름을 보여주며 학습하지 않습니다. uv tool의 Python 환경과 별도 Python 환경은 패키지를 공유하지 않으므로, 위 예제용 가상환경에도 패키지를 설치합니다. 두 세션의 재개 연습은 재개 예제를 참고하세요.

기록을 공유하기 전에

.autoresearch/와 보고서에는 직접 기록한 명령, 파일 경로, 로그 발췌, 근거가 포함될 수 있습니다. 커밋·업로드 전에 비밀 키, 개인 데이터, 비공개 데이터셋·로그를 확인하세요. CLI의 JSON 검사는 비밀정보 탐지나 자동 익명화를 제공하지 않습니다. 원본 증거를 수정하면 저장된 해시와 달라질 수 있으므로 공개용 사본을 따로 만드세요.

잠금이 남아 있으면 실행 중인 CLI가 없는지 확인한 뒤 복구하세요. .autoresearch/.lock이나 프로젝트 루트의 .autoresearch.init.lock을 무조건 지우지 않습니다. 기록 이력이 크면 context를 먼저 사용하세요. report와 lineage의 전체 출력에는 크기 제한이 없습니다.

더 알아보기

• 에이전트 설치·호출·문제 해결
• 설치·업데이트·스킬 갱신
• 처음 설정부터 중단·재개까지
• 연구 절차와 판단 규칙
• 프로젝트 연결·환경 설정
• 기록 규모별 성능 측정과 한계
• 제품 방향과 참고 연구
• 배포 파일 검증 · 기여·CI 기준

소프트웨어 검증은 합성 기록 중심이며 실제 ML 품질이나 학습 비용 절감을 보장하지 않습니다. 라이선스는 MIT입니다.