Ch3. 프로젝트 레이아웃과 Discovery
agent 디렉터리 슬롯이 source manifest로 변환되는 과정을 운영 관점에서 분석한다.
핵심 요약
agent/디렉터리는 권한, 컨텍스트, 실행 능력을 선언하는 인터페이스입니다.- Discovery가 path-derived identity를 만들기 때문에 파일명과 슬롯 구조가 곧 운영 계약입니다.
- root agent, subagent, instructions, skills, tools의 경계를 폴더 구조에서 먼저 강제해야 합니다.
Eve에서 agent/는 단순 폴더가 아니라 권한과 컨텍스트의 선언적 인터페이스입니다. Discovery가 이 인터페이스를 읽어 source manifest를 만들고, compiler가 이를 compiled manifest로 정규화합니다.
Root 해석: nested와 flat
discover/project.ts는 시작 경로에서 위로 올라가며 Eve 프로젝트를 찾습니다.
| 레이아웃 | 조건 | 권장도 |
|---|---|---|
| nested | app root에 package.json 등 project marker가 있고 agent/가 존재 | 권장 |
| flat | 현재 디렉터리 자체가 agent.ts, instructions.md, tools/ 등을 가짐 | 지원하지만 덜 권장 |
엔터프라이즈 프로젝트에서는 nested layout을 쓰는 것이 좋습니다.
my-enterprise-agent/
├── package.json
├── agent/
│ ├── agent.ts
│ ├── instructions.md
│ ├── tools/
│ ├── skills/
│ ├── connections/
│ ├── hooks/
│ ├── sandbox/
│ ├── channels/
│ └── subagents/
└── evals/앱 코드와 프론트엔드, 테스트, 인프라 설정을 agent surface와 분리할 수 있기 때문입니다.
Discovery가 읽는 슬롯
discover/discover-agent.ts는 root entries를 정렬해서 슬롯별 discovery로 보냅니다.
| 슬롯 | root 지원 | subagent 지원 | 운영상 의미 |
|---|---|---|---|
agent.ts | 예 | 예 | 모델, outputSchema, compaction, experimental flags |
instructions.md/ts/ | root 필수 | subagent 선택 | always-on prompt |
tools/ | 예 | 예 | app runtime 실행 권한 |
skills/ | 예 | 예 | on-demand 절차와 참고 파일 |
connections/ | 예 | 예 | 외부 MCP/OpenAPI 접근 |
hooks/ | 예 | 예 | event stream side effect |
sandbox.ts 또는 sandbox/sandbox.ts | 예 | 예 | shell/file 실행 격리 설정 |
sandbox/workspace/** | 예 | 예 | session bootstrap seed files |
channels/ | root만 | 아니오 | 외부 delivery surface |
schedules/ | root만 | 아니오 | cron-initiated work |
subagents/ | 예 | 예 | child agent graph |
lib/ | import-only | 예 | shared authored code |
여기서 lib/는 runtime workspace에 mount되지 않습니다. 모델이 읽을 파일은 skills/나 sandbox/workspace/에 넣어야 합니다.
Path-derived identity
Eve definition에는 name이나 id 필드를 쓰지 않습니다. identity는 path에서 나옵니다.
| 파일 | 모델/런타임 이름 |
|---|---|
agent/tools/run_report.ts | run_report |
agent/connections/salesforce.ts | salesforce |
agent/hooks/audit/log.ts | audit/log |
agent/subagents/reviewer/agent.ts | reviewer |
agent/schedules/billing/sweep.ts | billing/sweep |
그래서 파일명이 곧 public contract입니다. 한번 배포한 tool name은 eval, trace, approval ledger, prompt behavior에 그대로 남습니다. rename은 breaking change로 다뤄야 합니다.
Discovery diagnostic을 운영 artifact로 취급한다
compileAgent()는 discovery diagnostic이 error이면 CompileAgentError를 던지지만, artifact는 먼저 써둡니다. 덕분에 실패한 빌드도 들여다볼 수 있습니다.
| Artifact | 확인할 것 |
|---|---|
.eve/agent-discovery-manifest.json | 어떤 source file이 발견됐는가 |
.eve/diagnostics.json | unsupported slot, invalid name, shape error |
.eve/compiled-agent-manifest.json | runtime이 읽을 최종 표면 |
.eve/module-map.mjs | compiled module entrypoint |
프로덕션 CI에서는 eve build 실패 로그만 보지 말고 diagnostics artifact를 같이 보존하세요. 에이전트 표면은 보안 감사 대상이라, “왜 빌드가 실패했는가”보다 “어떤 권한 표면을 만들려고 했는가”가 더 중요할 때가 많습니다.
Instructions discovery 전략
Eve는 instructions를 세 가지 형태로 받습니다.
| 형태 | 용도 |
|---|---|
instructions.md | 가장 단순한 always-on prompt |
instructions.ts | build-time composition |
instructions/ | 여러 markdown/module source 조합 |
엔터프라이즈에서는 instructions.md를 짧게 유지하고 긴 절차는 skills/로 옮기세요. always-on prompt가 커지면 token cost와 context drift도 함께 커집니다.
좋은 분리:
instructions.md
- 역할, 보안 원칙, 답변 품질 기준
skills/release-checklist/SKILL.md
- 릴리즈 절차, QA 항목, rollback 절차
tools/create_release.ts
- 실제 릴리즈 생성 API 호출Skills discovery: progressive disclosure의 단위
Eve skill은 flat markdown 또는 packaged skill을 지원합니다.
agent/skills/forecast.md
agent/skills/research/SKILL.md
agent/skills/research/references/checklist.md
agent/skills/research/scripts/collect.tspackaged skill의 sibling files는 runtime workspace에 seed되어 모델이 파일 도구로 읽을 수 있습니다. 긴 지식을 prompt에 직접 붙이는 대신 필요할 때 읽게 하는 구조입니다.
엔터프라이즈 skill 규칙:
description은 제목이 아니라 trigger condition으로 쓴다.- one skill = one operational playbook으로 제한한다.
- skill 안의 scripts는 직접 실행 가능하므로 코드 리뷰 대상이다.
- regulated domain 지식은 version/date/source를 frontmatter 또는 body에 명시한다.
Subagent discovery와 경계
agent/subagents/<id>/agent.ts는 child agent의 root입니다. declared subagent는 root agent의 슬롯을 상속하지 않습니다. 품질과 보안 양쪽에서 중요한 지점입니다.
| 잘못된 기대 | 실제 동작 |
|---|---|
| root의 tools가 subagent에도 보인다 | 보이지 않음 |
| root의 skills가 subagent에도 보인다 | 보이지 않음 |
| root sandbox seed가 subagent에도 적용된다 | 적용되지 않음 |
| root state가 subagent에도 이어진다 | 이어지지 않음 |
그래서 subagent는 권한을 좁히는 데 유용합니다. 예를 들어 researcher에게는 read-only connection만 주고 operator에게는 승인형 write tool만 주는 식입니다.
Discovery 체크리스트
새 Eve 에이전트를 리뷰할 때 다음을 확인합니다.
| 항목 | 기준 |
|---|---|
| layout | nested layout 사용 |
| tool names | 위험도와 도메인이 이름에 드러남 |
| unsupported dirs | .eve/diagnostics.json에 warning/error 없음 |
| root-only slots | subagent 안에 channels/schedules 없음 |
| instructions | root prompt가 짧고 장기 절차는 skills로 분리 |
| sandbox workspace | seed file에 secret, token, customer data 없음 |
| connections | allow/block filter와 approval 정책 명시 |
| evals | agent/ 변경과 함께 behavior gate 추가 |
Discovery는 Eve 내부 구현 단계이지만, 엔터프라이즈에서는 “에이전트 권한 인벤토리 생성기”로 써먹어야 합니다.