vectorize-io/self-driving-agents 딥다이브
— 179명의 "기억하는 직원"을 한 줄 명령으로 고용하기

1프로젝트 한 줄 요약

"미리 잘 써둔 179명의 전문가 프롬프트를, 세션이 끝나도 기억을 잃지 않는 '진짜 직원'으로 만들어 원하는 AI 툴에 꽂아주는 설치기"다.

구체적으로 CLI가 하는 일은 세 가지다. ① 179개 페르소나 중 원하는 것을 골라(부서/직무 경로로 지정), ② 지정한 하네스에 맞는 형식(스킬 zip · 플러그인 · MCP · Python 툴)으로 변환·설치하고, ③ 그 에이전트를 Hindsight 메모리 뱅크에 연결한다. CLI 자체는 LLM을 호출하지 않는다 — 어디까지나 준비·배선(wiring) 작업만 한다.

# 마케팅 부서의 SEO 에이전트를 Claude(Chat/Cowork) 하네스에 설치
npx @vectorize-io/self-driving-agents install marketing/seo --harness claude

# 내가 만든 로컬 에이전트를 Claude Code에, 기억 뱅크는 비운 채로 설치
npx @vectorize-io/self-driving-agents install ./my-agent --harness claude-code --empty

2왜 주목받는가 — "기억하는 프롬프트 모음"

GitHub에는 "복사해서 쓰는 프롬프트 100선" 류 저장소가 넘친다. 이들의 치명적 한계는 기억이 없다는 것이다. 어제 이 에이전트에게 "우리 코드베이스는 pnpm을 쓴다"고 알려줘도, 오늘 새 세션에서는 다시 npm을 제안한다. 매번 처음부터 설명해야 한다.

이 저장소의 차별점은 모든 에이전트를 Hindsight 기억 서버에 자동 연결한다는 점이다. 대화 내용에서 "안정적인 사실"만 걸러 저장하고, 그것을 바탕으로 지식 페이지를 스스로 갱신한다. 여기에 더해 한 번의 install 명령이 성격이 전혀 다른 5개 실행 환경을 모두 지원한다.

3기술 스택 전체 지도

핵심을 먼저 짚으면, 이 저장소는 "작은 TypeScript CLI + 수백 개의 마크다운/JSON 데이터 파일 + 별도 문서 사이트" 구조다. 무거운 로직은 거의 없고, 대부분이 사람이 읽는 프롬프트와 설정이다.

① CLI 본체 (TypeScript)

② 기억 백엔드 (Hindsight — 별도 저장소)

CLI가 연결하는 대상. github.com/vectorize-io/hindsight에 있는 별도 서버 제품이며, 두 가지 데이터 원소를 다룬다 — Memories(추가만 되는 원자적 사실)와 Knowledge pages(배경에서 다시 쓰여지는 마크다운 문서). 클라우드(api.hindsight.vectorize.io) 또는 셀프호스팅으로 띄운다.

③ 하네스별 통합 코드

• Hermes 플러그인 — hermes-plugin/__init__.py + plugin.yaml. Python으로 agent_knowledge_* 툴을 등록(httpx로 Hindsight REST 호출).
• Claude Code — vectorize-io/hindsight 마켓플레이스의 hindsight-memory 플러그인을 설치·배선.
• Claude Chat/Cowork — src/skill/SKILL.md를 zip으로 묶어 스킬로 제공.

④ 문서/마케팅 사이트

• website/ — Next.js(App Router) + Tailwind. Mermaid로 아키텍처 다이어그램을 그린다. GitHub Pages로 배포(public/CNAME).

⑤ 검증 도구

• src/scripts/lint-bank-templates.mjs — 저장소 안 모든 bank-template.json을 검사. 폐기된 reflect_mission 필드 금지, observations_mission 필수 등 규칙을 강제. npm run lint로 실행.

4아키텍처 심화 — 기억 vs 지식, 그리고 5개 하네스

큰 그림

핵심 설계 1 — source_query로 페이지를 "다시 답하기"

각 지식 페이지에는 source_query가 붙어 있다. 이건 "이 페이지가 답해야 하는 질문"이다. 새 기억이 쌓여 통합 사이클이 돌면, 시스템은 그 질문을 다시 답해서 페이지를 새로 써 내려간다. 즉 페이지는 "손으로 고치는 문서"가 아니라 "질문의 최신 답변"으로 취급된다. src/skill/SKILL.md의 설명을 그대로 보면:

---
name: agent-knowledge
description: Your long-term knowledge pages. Read them at session start...
---
**How it works:** Your conversations are automatically retained into a
Hindsight memory bank. The system extracts observations and uses them to
keep your pages current. Each page has a "source query" — a question the
system re-answers after every consolidation cycle to rebuild the page.

핵심 설계 2 — "무엇을 기억하지 말지"를 선언하기

좋은 기억 시스템의 절반은 버릴 것을 정하는 규칙이다. engineering/bank-template.json은 "안정적 사실만 남기고 일회성 디버깅은 무시하라"고 못박는다:

"observations_mission": "Observations are stable facts about the codebase,
stack, conventions, ownership, deployment topology, performance baselines,
and recurring failure modes. Ignore one-off debugging sessions and
ephemeral build issues."

핵심 설계 3 — 하나의 CLI, 다섯 개의 서로 다른 배선

src/cli.ts는 하네스마다 완전히 다른 방식으로 기억을 붙인다. 이게 이 저장소에서 가장 배울 만한 엔지니어링이다.

설치 시 에이전트를 어디서 가져오나

에이전트 소스는 세 가지다 — ① 내장 뱅크(저장소 자체), ② 로컬 디렉터리, ③ org/repo/path 형식의 GitHub 경로. GitHub의 경우 git clone이 아니라 archive/refs/heads/main.tar.gz를 curl | tar xz로 받아 푼다(설치 시점에 git 불필요).

5디렉토리 구조 해부

포인트는 "코드는 src/에만 조금 있고, 저장소 대부분은 부서 폴더 안의 마크다운·JSON 데이터"라는 것이다. 즉 이건 소프트웨어라기보다 잘 구조화된 프롬프트 데이터셋 + 얇은 설치 도구에 가깝다.

주요 파일과 실제 역할

페르소나 파일은 어떻게 생겼나

에이전트 하나는 프런트매터(이모지·색·성격) + 미션 + 체크리스트로 된 마크다운이다. 예를 들어 code-reviewer.md의 리뷰 원칙 부분:

1. **Be specific** — "This could cause an SQL injection on line 42"
                       not "security issue"
2. **Explain why** — Don't just say what to change, explain the reasoning
3. **Suggest, don't demand** — "Consider using X because Y" not "Change this to X"
4. **Prioritize** — Mark issues as 🔴 blocker, 🟡 suggestion, 💭 nit

그리고 specialized/exec-ops/agents-orchestrator.md는 여러 하위 에이전트를 하나의 개발 파이프라인으로 지휘하는 "메타 에이전트"인데, 품질 게이트를 통과해야만 다음 단계로 넘어가는 루프를 명시한다:

### Implement Continuous Quality Loops
- **Task-by-task validation**: Each task must pass QA before proceeding
- **Automatic retry logic**: Failed tasks loop back to dev with feedback
- **Quality gates**: No phase advancement without meeting standards
- **Failure handling**: Maximum retry limits with escalation procedures

6학습 포인트 — 여기서 훔쳐올 설계

7시스템 요구사항

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

원본

• vectorize-io/self-driving-agents — 본 저장소(README에 179 로스터·설치 원라이너)
• selfdrivingagents.ai — 문서/마케팅 사이트(개념·하네스·에이전트 목록)
• vectorize-io/hindsight — 기억 서버(이 프로젝트의 진짜 엔진)

기반 개념

• Model Context Protocol (MCP) — 에이전트 툴 연결 표준
• Claude Code — 대표 하네스, 수명주기 훅·플러그인
• @clack/prompts — 대화형 CLI UI
• Vitest — CLI 테스트에 쓰인 러너