이 게시물은 Hermes Agent Challenge: Build With Hermes Agent를 위한 제출물입니다.

Hermes Repo Dojo: 대부분의 에이전트는 답변하지만, Hermes는 학습하고 안전하게 기여합니다.

어떤 GitHub 저장소(repo)든 살아있는 온보딩 아카데미로 바꾸세요.

대부분의 AI 코딩 에이전트(coding agents)는 저장소에 관한 질문에 답변합니다.

Hermes Repo Dojo는 다른 것을 수행합니다.

이 도구는 Hermes Agent가 GitHub 저장소를 학습하고, 그 이해도를 재사용 가능한 저장소 특화 기술(repo-specific skills)로 변환하며, 두 번째 패스(second pass)를 통해 개선하고, 샌드박스(sandbox) 클론 내부에서 안전하게 첫 번째 기여(contribution)를 생성할 수 있게 합니다.

이것은 저장소 챗봇(repo chatbot)이 아닙니다.

이것은 에이전트 기반 온보딩 시스템(agentic onboarding system)입니다.

내가 만든 것

Hermes Repo Dojo는 모든 공개 GitHub 저장소를 새로운 기여자(contributor)를 위한 가이드형 온보딩 아카데미로 변환하는 로컬 AI 개발자 도구입니다.

사용자가 GitHub 저장소 URL을 붙여넣으면, Hermes Repo Dojo는 다음을 생성합니다:

• 🧬 Repo DNA — 목적, 스택(stack), 언어, 명령어 및 엔트리포인트(entrypoints)
• 🏗️ Architecture Map — 코드베이스의 논리적 영역
• 🧭 Setup Timeline — 무엇을 먼저, 두 번째로, 그리고 다음에 해야 하는지에 대한 순서
• 🥋 Dojo Map — 탐색자(Explorer)에서 기여자(Contributor)로 이어지는 기여자의 학습 경로
• ⚔️ Boss Fight — 수락 기준(acceptance criteria)이 포함된 범위가 지정된 첫 번째 기여
• 🧠 Skill Forge — 재사용 가능한 저장소 특화 Hermes 기술
• 🔁 Second Pass — 생성된 기술을 사용한 개선 전/후 비교
• 🛡️ Patch Arena — Hermes가 첫 번째 기여를 생성하는 안전한 샌드박스(sandbox)
• 🎬 Hermes Brain Replay — 에이전트의 학습 추적(learning trace)을 시각적으로 재현한 리플레이

핵심 아이디어:

저장소는 단순히 코드를 저장하는 곳이어야 해서는 안 됩니다. 저장소는 가르쳐야 합니다. 기억해야 합니다. 그리고 기여를 안전하게 안내해야 합니다.

문제점

오픈 소스 온보딩(onboarding)은 망가져 있습니다.

모든 새로운 기여자는 보통 동일하고 고통스러운 탐색 과정을 반복해야 합니다:

• README 읽기
• 아키텍처 (architecture) 추측하기
• 적절한 엔트리포인트 (entrypoints) 찾기
• 설치 및 테스트 명령 확인하기
• 컨벤션 (conventions) 이해하기
• 안전한 첫 기여 (contribution)가 무엇인지 결정하기

메인테이너 (Maintainers)와 시니어 기여자 (senior contributors)들은 머릿속에 숨겨진 지식을 가지고 있습니다.

새로운 기여자들은 그렇지 않습니다.

AI 에이전트 (AI agents)는 저장소 (repo)에 관한 질문에 답할 수 있지만, 그 지식의 대부분은 답변이 끝난 후 사라집니다.

Hermes Repo Dojo는 이러한 일회성 탐색 과정을 재사용 가능한 운영 지식 (operational knowledge)으로 전환합니다.

데모 (Demo)

🎥 데모 영상:

데모에서 저는 다음을 사용합니다:

Hermes Repo Dojo는 아주 작은 교육용 자동 미분 (autograd) 엔진인 micrograd를 분석하여 다음을 생성합니다:

• 스택 (Stack): Python, Autograd, Neural Networks, Pytest
• 아키텍처 (Architecture):
  • 핵심 자동 미분 엔진 (Core Autograd Engine)
  • 신경망 라이브러리 (Neural Network Library)
  • 테스트 및 데모 (Tests and Demos)
• 기술 (Skills):
  • MicrogradAutogradTrace
  • MicrogradMLPTraining
  • MicrogradGraphViz
• 패치 아레나 (Patch Arena) 기여:
  • Value 클래스에 sigmoid 활성화 함수 추가
  • 스모크 테스트 (smoke test) 생성
  • 디프 (diff) 표시
  • 패치 (patch) 검증

최종 데모 흐름은 다음과 같습니다:

GitHub URL
   ↓
Hermes 저장소 분석 (Hermes Repo Analysis)
...

코드 (Code)

GitHub 저장소:

https://github.com/jpablortiz96/hermes-repo-dojo

나의 기술 스택 (My Tech Stack)

• Hermes Agent CLI
• Hermes 터미널 툴셋 (terminal toolset)
• Hermes 기술 툴셋 (skills toolset)
• Next.js
• TypeScript
• Tailwind CSS
• Node.js API routes
• 로컬 JSON 영속성 (Local JSON persistence)
• 샌드박스화된 Git 워크스페이스 (Sandboxed Git workspaces)

이 앱은 로컬에서 실행되며 백엔드에서 CLI를 통해 Hermes를 호출합니다.

Hermes Agent 사용 방법

Hermes Agent는 이 프로젝트에서 장식적인 요소가 아닙니다.

그것은 워크플로 (workflow) 뒤에 있는 운영 지능 (operating intelligence)입니다.

Hermes Repo Dojo는 다음과 같은 명령을 통해 Hermes를 호출합니다:

hermes chat --toolsets "terminal,skills" -q "..."

Hermes는 다음을 위해 사용됩니다:

Hermes는 다음을 위해 사용됩니다:

• 클론된 저장소(cloned repositories) 조사
• 아키텍처(architecture) 및 저장소 구조에 대한 추론
• 구조화된 온보딩(onboarding) 분석 생성
• 재사용 가능한 저장소 특화 기술(repo-specific skills) 생성
• 두 번째 실행 시 온보딩 흐름 개선
• 안전한 기여 계획 수립 지원
• 제품 이면에 있는 에이전트 학습 내러티브(agent learning narrative) 구동

제가 의존했던 핵심 Hermes 기능은 다음과 같습니다:

Hermes 기능	Repo Dojo 활용 방식
터미널 도구 사용 (Terminal tool use)	로컬 클론 저장소 조사
...

핵심 아이디어 (The Big Idea)

모든 저장소가 스스로를 가르칠 수 있다면 어떨까요?

저장소는 보통 정적(static)입니다.

코드를 저장하지만, 그 코드 이면에 있는 기여자의 여정(contributor journey)은 보존하지 못합니다.

Hermes Repo Dojo는 저장소를 운영 가능한(operational) 상태로 만듭니다.

Hermes 에이전트(Hermes Agent)가 코드베이스를 조사하고, 숨겨진 온보딩 지식을 추출하며, 해당 지식을 재사용 가능한 기술(skills)로 변환하고, 그 기술을 사용하여 향후 더 나은 상호작용을 안내할 수 있도록 합니다.

그 결과, 단순히 코드만 포함하는 저장소가 아닌,

살아있는 온보딩 워크플로우(onboarding workflow)가 됩니다.

핵심 기능 (Core Features)

🧬 저장소 DNA (Repo DNA)

Hermes는 저장소 프로필을 추출합니다:

• 요약 (Summary)
• 주요 언어 (Main language)
• 스택 (Stack)
• 엔트리포인트 (Entrypoints)
• 명령어 (Commands)
• 중요 파일 (Important files)
• 아키텍처 영역 (Architecture areas)

micrograd의 경우, Hermes는 Python, Autograd, Neural Networks, Pytest 및 기여자가 가장 먼저 조사해야 할 핵심 파일들을 식별합니다.

🏗️ 아키텍처 맵 (Architecture Map)

Hermes는 가공되지 않은 폴더를 보여주는 대신, 구조를 논리적인 영역으로 변환합니다.

micrograd에 대해 다음과 같이 매핑합니다:

• Core Autograd Engine — micrograd/engine.py
• Neural Network Library — micrograd/nn.py
• Tests and Demos — demo.ipynb, trace_graph.ipynb, test/test_engine.py

🧠 기술 대장간 (Skill Forge)

이 단계에서 프로젝트는 단순한 분석 그 이상이 됩니다.

Hermes는 재사용 가능한 저장소 특화 기술(repo-specific skills)을 생성합니다.

데모를 위해 다음과 같은 기술을 생성합니다:

MicrogradAutogradTrace
MicrogradMLPTraining
MicrogradGraphViz

핵심은 간단합니다:

저장소 이해(Repository understanding)는 단 한 번의 답변으로 사라져서는 안 됩니다. 그것은 재사용 가능한 운영 지식(operational knowledge)이 되어야 합니다.

🔁 Second Pass (두 번째 패스)

기술(skills)을 생성한 후, Hermes Repo Dojo는 두 번째 패스(second pass)를 실행합니다.

기술 생성 전:

• 기여자가 README 파일을 수동으로 읽음
• 명확한 경로 없이 파일을 조사함
• 어디서 시작할지 추측함

기술 생성 후:

• Hermes가 중요한 파일들을 파악함
• Hermes가 저장소별 특화된 절차(repo-specific procedures)를 보유함
• Hermes가 범위가 지정된 첫 번째 기여(scoped first contribution)를 안내할 수 있음

대부분의 에이전트(agents)는 한 번 답변하고 끝납니다.

Hermes는 두 번째 패스에서 개선됩니다.

🛡️ Patch Arena (패치 아레나)

Patch Arena는 Hermes가 안전하게 기여할 수 있는 공간입니다.

이것은 무모한 자동 코딩(auto-coding)이 아닙니다.

Patch Arena는 샌드박스 클론(sandbox clone)을 생성합니다:

workspace/patch-arena/{repo}-{timestamp}

그 후 Hermes는 오직 해당 샌드박스 내부에서만 기여를 생성하거나 지원할 수 있습니다.

안전 규칙:

• 원본 저장소는 절대 수정되지 않음
• git push 금지
• sudo 금지
• apt-get 금지
• 파괴적인 명령(destructive commands) 금지
• 패치가 제시되기 전에 Diff(차이점)를 보여줌
• 결과를 보여주기 전에 검증(Verification)을 실행함

micrograd의 경우, Patch Arena는 안전한 첫 번째 기여를 생성합니다:

+ import math
+
  class Value:
...

또한 스모크 테스트(smoke test)를 추가하고 결과를 검증합니다.

이 순간이 바로 이 제품이 단순한 온보딩 대시보드(onboarding dashboard) 그 이상이 되는 지점입니다.

Hermes는 단순히 저장소를 설명하는 것에 그치지 않습니다.

안전한 첫 번째 기여를 만들어냅니다.

🎬 Hermes Brain Replay (Hermes 브레인 리플레이)

대부분의 에이전트 시스템은 프로세스를 로그(logs) 속에 숨깁니다.

Hermes Brain Replay는 에이전트의 여정을 가시적인 제품 경험으로 전환합니다.

다음과 같은 과정을 보여줍니다:

Repo Ingested (저장소 수집됨)
DNA Extracted (DNA 추출됨)
Architecture Mapped (아키텍처 매핑됨)
...

이는 에이전트의 학습 과정을 이해하기 쉽고, 시각적이며, 데모하기 좋게 만들기 위해 설계되었습니다.

Architecture (아키텍처)

flowchart TD
    A[GitHub Repo URL] --> B[Next.js UI]
    B --> C[Analyze API]
...

Safety Model (안전 모델)

Hermes Repo Dojo는 학습(learning)과 기여(contribution)를 분리합니다.

Scout Mode (스카우트 모드)

Scout Mode는 읽기 중심(read-oriented)입니다.

저장소를 조사하고, 사실 관계를 추출하며, 온보딩 분석(onboarding analysis)을 생성하고, 기술을 연마합니다.

Patch Arena (패치 아레나)

Patch Arena는 쓰기(write)가 가능하지만, 오직 샌드박스(sandbox) 클론 내부에서만 작동합니다.

원본 저장소는 전혀 손상되지 않은 상태로 유지됩니다.

Demo-safe fallback (데모 안전 폴백)

에이전트 제공업체(Agent providers)는 할당량 초과(quota), 타임아웃(timeout)이 발생하거나 안전하지 않은 출력을 반환할 수 있습니다.

제품의 신뢰성을 유지하기 위해, Hermes Repo Dojo는 로컬에서 추출된 저장소 사실 관계와 샌드박스 내에서 안전한 패치 생성 방식으로 폴백(fallback)할 수 있습니다.

이 폴백은 Hermes Agent를 대체하는 것이 아닙니다. 제공업체의 제한 사항이 실시간 흐름을 방해할 때 사용자 경험과 환경을 보호하는 역할을 합니다.

차별점

일반적인 AI 저장소 도구	Hermes Repo Dojo
일회성 질문에 답변	재사용 가능한 저장소 특화 기술 생성
...

이것은 저장소를 위한 챗봇이 아닙니다.

이것은 에이전트 기반(agentic) 온보딩 시스템입니다.

배운 점

이 프로젝트를 구축하며 에이전트 기반 제품에는 모델의 출력 그 이상이 필요하다는 것을 배웠습니다.

다음과 같은 요소들이 필요합니다:

• 명확한 워크플로우 (workflows)
• 안전 경계 (safety boundaries)
• 가시적인 추론 결과물 (visible reasoning artifacts)
• 재사용 가능한 지식 (reusable knowledge)
• 시간이 지남에 따라 개선 사항을 보여줄 수 있는 방법

Hermes Agent는 이 프로젝트에 매우 적합했습니다. 왜냐하면 이 프로젝트는 단순히 텍스트를 생성하는 것에 관한 것이 아니기 때문입니다.

이것은 도구 사용(tool use), 기술 생성, 저장소 이해, 그리고 다단계 워크플로우(multi-step workflows)에 관한 것입니다.

향후 계획

다음 버전에는 다음과 같은 기능이 포함될 수 있습니다:

• GitHub 풀 리퀘스트(pull request) 생성
• 유지 관리자 승인 기여 템플릿 (Maintainer-approved contribution templates)
• 다중 저장소 조직 온보딩 (Multi-repo organization onboarding)
• 팀 기술 라이브러리 (Team skill libraries)
• VS Code 확장 프로그램 (extension)
• CI 통합 (CI integration)
• 저장소 상태 점수 산정 (Repo health scoring)
• 기여자 진행 상황 추적 (Contributor progress tracking)
• 엔터프라이즈 내부 저장소 아카데미 모드 (Enterprise internal repo academy mode)

최종 요약

대부분의 에이전트는 답변합니다.

Hermes는 학습합니다.

그리고 안전하게 기여합니다.