# Refactor: agent / skills / tools DX 개선 plan > 한 번의 작업 세션으로 codex가 처음부터 끝까지 수행할 수 있도록 작성된 단일 PR plan. --- ## 목표 지금 구조는 컨셉상 "agent ⊃ skills ⊃ tools"인데 실제 코드가 다음과 같이 어긋나 있다. 1. `src/tools/builtins/`의 5개 tool은 전부 onboarding 전용인데도 글로벌 폴더에 위치 2. tool 파일이 `@skills/onboarding/*`을 import (의존 방향이 거꾸로) 3. `OnboardingSkill`이 모든 tool을 `createBuiltInToolRegistry().list()`로 받아 `selectToolsForDerived()`에서 **이름 문자열로** 필터 → 오타에 무방비 4. `runtime/tool-loop.ts`는 generic LLM↔tool loop인데 onboarding 폴더 안에 갇혀 있음 5. `Skill` 인터페이스가 `name/canHandle/handle` 3줄뿐 — 새 skill이 어떻게 자기 tool을 선언할지 가이드 없음 6. skill의 의존성 조립이 `main.ts`에 노출 — skill 폴더에 entry factory가 없음 이 plan을 끝내면: - onboarding-tool은 onboarding 폴더 안에서 self-contained - tool→skill의 역방향 import 0건 - `selectToolsForDerived`가 tool 객체 직접 참조 (컴파일 타임 안전) - generic runtime은 `src/agent/runtime/`로 hoist - `Skill` 인터페이스에 `tools` 필드 추가 - `createOnboardingSkill(deps)` factory 도입 - `docs/skill-authoring.md`로 신규 skill/tool 추가 절차 문서화 --- ## 최종 구조 ``` src/ agent/ agent.ts types.ts index.ts runtime/ tool-loop.ts ← hoisted from skills/onboarding/runtime tool-loop.test.ts ← hoisted tools/ tool.ts ← ToolContext에서 OnboardingSession 제거, generic param 추가 registry.ts parser.ts parser.test.ts serializer.ts index.ts (builtins/ 폴더 삭제) skills/ skill.ts ← tools: readonly Tool[] 추가 onboarding/ index.ts ← createOnboardingSkill(deps) factory export skill.ts ← tool을 직접 import, selectToolsForDerived 객체 참조 session.ts types.ts constants.ts message-filter.ts onboarding-templates.ts tools/ ← NEW: onboarding 전용 tool 모음 index.ts ← createOnboardingToolRegistry, ALL_TOOLS export context.ts ← OnboardingToolContext validate-nickname.ts check-onboarding-progress.ts check-onboarding-progress.test.ts lookup-community-rule.ts get-room-context.ts verify-discord-nickname.ts verify-discord-nickname.test.ts prompts/ ← 변경 없음 runtime/ ← tool-loop만 빠짐 orchestrator.ts ← import 경로 갱신 orchestrator.test.ts critic.ts validator.ts validator.test.ts planner-schema.ts trace.ts state/ ← 변경 없음 docs/ skill-authoring.md ← NEW ``` --- ## 변경 사항 상세 ### 1. `src/tools/tool.ts` — ToolContext에서 onboarding 의존성 제거 + Tool generic화 **before** ```ts import type { GarnetClient } from "@common/garnet"; import type { NatsClient } from "@common/nats"; import type { RoomContextService } from "@room/room-context-service"; import type { ZodType } from "zod"; import type { OnboardingSession } from "@skills/onboarding/types"; export interface ToolContext { chatroomId?: string | undefined; natsClient?: Pick | undefined; userId?: string | undefined; session?: OnboardingSession | null | undefined; garnetClient?: GarnetClient | undefined; roomContextService?: RoomContextService | undefined; } export interface Tool { name: string; description: string; argsSchema: ZodType; resultSchema: ZodType; execute(args: A, ctx: ToolContext): Promise; } ``` **after** ```ts import type { GarnetClient } from "@common/garnet"; import type { NatsClient } from "@common/nats"; import type { RoomContextService } from "@room/room-context-service"; import type { ZodType } from "zod"; export interface ToolContext { chatroomId?: string | undefined; natsClient?: Pick | undefined; userId?: string | undefined; garnetClient?: GarnetClient | undefined; roomContextService?: RoomContextService | undefined; } export interface Tool { name: string; description: string; argsSchema: ZodType; resultSchema: ZodType; execute(args: A, ctx: C): Promise; } ``` `@skills/onboarding/types` import 한 줄과 `session` 필드 한 줄을 삭제, `Tool`에 generic `C` 추가. default를 `ToolContext`로 두면 기존 `Tool` 호출도 그대로 유효. ### 2. `src/skills/onboarding/tools/context.ts` — 신규 파일 ```ts import type { ToolContext } from "@tools/tool"; import type { OnboardingSession } from "../types.js"; export interface OnboardingToolContext extends ToolContext { session?: OnboardingSession | null | undefined; } ``` ### 3. tool 5개 + test 2개 이동 git mv로 파일을 옮기고, 옮긴 파일의 내부 import 경로만 수정. | from | to | |---|---| | `src/tools/builtins/validate-nickname.ts` | `src/skills/onboarding/tools/validate-nickname.ts` | | `src/tools/builtins/check-onboarding-progress.ts` | `src/skills/onboarding/tools/check-onboarding-progress.ts` | | `src/tools/builtins/check-onboarding-progress.test.ts` | `src/skills/onboarding/tools/check-onboarding-progress.test.ts` | | `src/tools/builtins/lookup-community-rule.ts` | `src/skills/onboarding/tools/lookup-community-rule.ts` | | `src/tools/builtins/get-room-context.ts` | `src/skills/onboarding/tools/get-room-context.ts` | | `src/tools/builtins/verify-discord-nickname.ts` | `src/skills/onboarding/tools/verify-discord-nickname.ts` | | `src/tools/builtins/verify-discord-nickname.test.ts` | `src/skills/onboarding/tools/verify-discord-nickname.test.ts` | | `src/tools/builtins/index.ts` | (덮어쓰기, 아래 #4 참고) | 각 파일에서 import 경로를 다음 규칙으로 갱신: - `import type { Tool, ToolContext } from "../tool.js";` → `import type { Tool } from "@tools/tool";` → `import type { OnboardingToolContext } from "./context.js";` - `from "@skills/onboarding/onboarding-templates"` → `from "../onboarding-templates.js"` - `from "@skills/onboarding/constants"` → `from "../constants.js"` - `from "@skills/onboarding/types"` → `from "../types.js"` - `from "@skills/onboarding/session"` → `from "../session.js"` - `from "@skills/onboarding/state/progress"` → `from "../state/progress.js"` - `from "../../config.js"` → `from "../../../config.js"` (한 단계 깊어짐) - 테스트 파일도 동일한 규칙 + 새 위치 기준으로 sibling import 경로 사용 각 tool의 export 시그니처를 `Tool` → `Tool`로 변경. `ctx` 파라미터를 사용하는 함수(`persistDiscordMemberId(memberId, ctx)` 등) 내부 타입도 맞춰서 `OnboardingToolContext`로 갱신. ### 4. `src/skills/onboarding/tools/index.ts` — 신규 (구 `tools/builtins/index.ts` 대체) ```ts import type { Tool } from "@tools/tool"; import { ToolRegistry } from "@tools/registry"; import type { OnboardingToolContext } from "./context.js"; import { checkOnboardingProgressTool } from "./check-onboarding-progress.js"; import { getRoomContextTool } from "./get-room-context.js"; import { lookupCommunityRuleTool } from "./lookup-community-rule.js"; import { validateNicknameTool } from "./validate-nickname.js"; import { verifyDiscordNicknameTool } from "./verify-discord-nickname.js"; export const onboardingTools = { validateNickname: validateNicknameTool, checkOnboardingProgress: checkOnboardingProgressTool, lookupCommunityRule: lookupCommunityRuleTool, getRoomContext: getRoomContextTool, verifyDiscordNickname: verifyDiscordNicknameTool, } as const; export const onboardingToolList: readonly Tool[] = [ validateNicknameTool, checkOnboardingProgressTool, lookupCommunityRuleTool, getRoomContextTool, verifyDiscordNicknameTool, ]; export function createOnboardingToolRegistry(): ToolRegistry { return new ToolRegistry() .register(validateNicknameTool) .register(checkOnboardingProgressTool) .register(lookupCommunityRuleTool) .register(getRoomContextTool) .register(verifyDiscordNicknameTool); } export { checkOnboardingProgressTool, getRoomContextTool, lookupCommunityRuleTool, validateNicknameTool, verifyDiscordNicknameTool, }; export type { OnboardingToolContext } from "./context.js"; ``` ### 5. 빈 `src/tools/builtins/` 폴더 삭제 ```bash rm -rf src/tools/builtins ``` ### 6. `src/skills/onboarding/skill.ts` — tool 객체 직접 참조 다음 import를 추가: ```ts import { checkOnboardingProgressTool, lookupCommunityRuleTool, onboardingToolList, validateNicknameTool, verifyDiscordNicknameTool, type OnboardingToolContext, } from './tools/index.js'; ``` 기존: ```ts import { createBuiltInToolRegistry } from '@tools/builtins/index'; import type { Tool, ToolContext } from '@tools/tool'; ``` → 다음으로 변경: ```ts import type { Tool } from '@tools/tool'; ``` (`ToolContext` 사용처는 모두 `OnboardingToolContext`로 교체) 생성자 내부: ```ts this.tools = createBuiltInToolRegistry().list(); ``` → ```ts this.tools = onboardingToolList; ``` `tools` 필드 타입을 `readonly Tool[]`로 변경. `buildToolContext(...)` 반환 타입을 `ToolContext` → `OnboardingToolContext`. `generateLlmText` 시그니처 옵션의 `toolContext?: ToolContext | undefined` → `OnboardingToolContext | undefined`. `tools?: readonly Tool[] | undefined` → `readonly Tool[] | undefined`. 핵심: `selectToolsForDerived`를 객체 참조로 다시 작성: ```ts private selectToolsForDerived( derived: DerivedState, ): readonly Tool[] { if (derived.intent.kind === 'discord-verify-question') { return [verifyDiscordNicknameTool]; } if (derived.phase.kind === 'nickname-rejected') { return [ validateNicknameTool, lookupCommunityRuleTool, checkOnboardingProgressTool, ]; } if (derived.intent.kind === 'status-question') { return [checkOnboardingProgressTool]; } if (derived.intent.kind === 'discord-question') { return [lookupCommunityRuleTool, verifyDiscordNicknameTool]; } return this.tools; } ``` 문자열 매칭(`tool.name === '...'`) 전부 제거. tool 이름 변경/삭제 시 컴파일 에러로 잡힌다. 마지막으로 클래스 상단에 `Skill` 인터페이스의 `tools` 필드를 노출: ```ts get tools(): readonly Tool[] { return onboardingToolList as readonly Tool[]; } ``` (또는 그냥 public 필드로 두어도 됨. 테스트 깨지지 않게 getter 권장.) ### 7. `src/skills/skill.ts` — 인터페이스에 tools 추가 ```ts import type { AgentRequest, AgentResponse, ConversationMessage } from "@agent/types"; import type { Tool } from "@tools/tool"; export interface Skill { readonly name: string; readonly tools: readonly Tool[]; canHandle(request: AgentRequest): boolean; handle( request: AgentRequest, conversationHistory: ConversationMessage[], ): Promise; } ``` ### 8. `src/agent/runtime/tool-loop.ts` — hoist `src/skills/onboarding/runtime/tool-loop.ts` → `src/agent/runtime/tool-loop.ts`로 이동. `src/skills/onboarding/runtime/tool-loop.test.ts` → `src/agent/runtime/tool-loop.test.ts`로 이동. 이동 후 import 경로 점검: - `import { parseToolCalls } from "@tools/parser";` 그대로 유효 - `import type { Tool, ToolContext } from "@tools/tool";` 그대로 유효 - `import { getActiveProcessTrace } from "./trace.js";` → - 결정 사항: `trace.ts`는 onboarding 전용이므로 hoist하지 않는다. - tool-loop가 trace 의존성을 가지면 안 됨. 따라서 **trace 호출을 옵션 콜백으로 일반화**: `tool-loop.ts` 변경: ```ts export interface ToolLoopOptions { // ...기존... onToolCallStart?: (call: { name: string; args: unknown }) => { finish: (result: { ok: boolean; resultSummary: string }) => void; }; } ``` 내부에서 `getActiveProcessTrace()?.startStep('tool-call')` 호출하던 자리를 `options.onToolCallStart?.(...)` 호출로 대체. orchestrator(onboarding 전용)에서 `runWithTools` 호출 시 `onToolCallStart` 콜백을 주입: ```ts import { runWithTools } from "@agent/runtime/tool-loop"; // ... return runWithTools({ // ...기존 옵션... onToolCallStart: ({ name, args }) => { const step = getActiveProcessTrace()?.startStep('tool-call'); return { finish: ({ ok, resultSummary }) => { step?.finish({ args, name, ok, resultSummary }); }, }; }, }); ``` orchestrator.ts에서: ```ts import { runWithTools } from "./tool-loop.js"; ``` → ```ts import { runWithTools } from "@agent/runtime/tool-loop"; ``` `ToolContext` import도 마찬가지로 그대로. `tool-loop.test.ts`도 mock 시나리오 점검 — trace 의존성 사라졌으므로 테스트는 단순화 가능하지만, 기능 회귀가 없다면 **테스트는 import 경로만 바꾸고 기존 시나리오 유지**. ### 9. `src/skills/onboarding/index.ts` — factory export 기존 (3줄짜리 re-export): ```ts export { OnboardingSkill } from './skill.js'; export type { OnboardingSession } from './types.js'; ``` 추가: ```ts import type { GarnetClient } from '@common/garnet'; import type { NatsClient } from '@common/nats'; import type { LlmClient } from '@llm/llm-client'; import type { RoomContextService } from '@room/room-context-service'; import type { ShadowEvalPublisher } from '@eval/shadow-bus'; import { OnboardingSkill } from './skill.js'; export interface CreateOnboardingSkillOptions { garnetClient: GarnetClient; llmClient: LlmClient; roomContextService?: RoomContextService; shadowEvalPublisher?: ShadowEvalPublisher; natsClient?: Pick; } export function createOnboardingSkill(opts: CreateOnboardingSkillOptions): OnboardingSkill { return new OnboardingSkill( opts.garnetClient, opts.llmClient, opts.roomContextService, opts.shadowEvalPublisher, opts.natsClient, ); } export { OnboardingSkill } from './skill.js'; export type { OnboardingSession } from './types.js'; ``` `OnboardingSkill` 클래스의 생성자 시그니처는 건드리지 않는다 (eval/runner.ts가 직접 생성하는 곳이 있어 호환 유지). ### 10. `src/main.ts` — factory 사용 기존 `src/main.ts:218-229`: ```ts const agent = new Agent(natsClient, conversationStore); const shadowEvalBus = new ShadowEvalBus(garnetClient); const onboardingSkill = new OnboardingSkill( garnetClient, llmClient, roomContextService, shadowEvalBus, natsClient, ); agent.registerSkill(onboardingSkill); ``` → ```ts const agent = new Agent(natsClient, conversationStore); const shadowEvalBus = new ShadowEvalBus(garnetClient); const onboardingSkill = createOnboardingSkill({ garnetClient, llmClient, roomContextService, shadowEvalPublisher: shadowEvalBus, natsClient, }); agent.registerSkill(onboardingSkill); ``` import 변경: ```ts import { OnboardingSkill } from '@skills/onboarding/index'; ``` → ```ts import { createOnboardingSkill } from '@skills/onboarding/index'; ``` ### 11. `src/eval/judges/process-judge.ts` — registry import 경로 갱신 ```ts import { createBuiltInToolRegistry } from "@tools/builtins/index"; ``` → ```ts import { createOnboardingToolRegistry } from "@skills/onboarding/tools/index"; ``` 호출부 `createBuiltInToolRegistry()` → `createOnboardingToolRegistry()`로 일괄 변경. ### 12. `src/eval/runner.ts` — 변경 없음 권장 `new OnboardingSkill(...)` 직접 호출 부분은 그대로 둔다 (factory만 main.ts에서 사용). 호환성 유지를 위해 클래스도 계속 export. ### 13. 그 외 영향받는 import 점검 (grep으로 확인) 다음 패턴이 남아 있으면 안 됨: - `@tools/builtins` (모두 `@skills/onboarding/tools` 또는 직접 import로 교체) - tool 파일 안의 `@skills/onboarding/*` (모두 relative `../...`로 교체) - `tool.name === '...'` 형태의 문자열 매칭 (객체 참조로 교체) 검증 명령: ```bash grep -rn "@tools/builtins" src # → 결과 0건이어야 함 grep -n "from \"@skills/onboarding" src/skills/onboarding/tools # → 결과 0건 (tool 파일이 자기 skill을 alias로 import 금지) grep -n "tool.name ===" src/skills # → 결과 0건 ``` ### 14. `docs/skill-authoring.md` — 신규 가이드 ```markdown # Skill / Tool 추가 가이드 ## 새 tool 추가 1. `src/skills//tools/.ts` 생성. 2. `Tool` 형태로 export. 3. `src/skills//tools/index.ts`의 `onboardingToolList` 같은 배열에 등록. 4. skill 파일에서 직접 import해 `selectToolsForDerived`(또는 동등한 메서드)에 객체로 추가. 5. tool은 절대 `@skills/...` alias로 다른 skill을 import하지 않는다 (relative import만 허용). ## 새 skill 추가 1. `src/skills//` 폴더 생성. 2. `Skill` 인터페이스(`src/skills/skill.ts`) 구현 — 최소한 `name`, `tools`, `canHandle`, `handle`. 3. `tools/` 서브폴더에 자기 tool 모음과 `ToolContext extends ToolContext`. 4. `index.ts`에 `createSkill(opts)` factory 추가. 5. `src/main.ts`의 bootstrap에서 factory 호출 후 `agent.registerSkill(...)`. 6. LLM↔tool 루프가 필요하면 `@agent/runtime/tool-loop`의 `runWithTools` 재사용. ## 어디를 보면 되나 - agent 디스패처: `src/agent/agent.ts` - skill 인터페이스: `src/skills/skill.ts` - generic tool 인터페이스: `src/tools/tool.ts` - generic LLM↔tool 루프: `src/agent/runtime/tool-loop.ts` - onboarding skill 구현: `src/skills/onboarding/` - onboarding tool 모음: `src/skills/onboarding/tools/` ``` --- ## 실행 순서 (codex가 그대로 따라가도록) 각 단계는 끝나면 다음 단계로 넘어가기 전에 typecheck를 돌릴 수 있다 (선택). 1. **`src/tools/tool.ts` 수정**: `OnboardingSession` import 제거, `session` 필드 제거, `Tool`에 generic `C extends ToolContext = ToolContext` 추가. 2. **새 폴더 생성**: `src/skills/onboarding/tools/`, `src/agent/runtime/`. 3. **`src/skills/onboarding/tools/context.ts` 작성** (위 #2 내용). 4. **tool 5개 + test 2개 이동** (`git mv`로). 각 파일 import 경로 갱신 + 시그니처 `Tool`로 변경. 5. **`src/skills/onboarding/tools/index.ts` 작성** (위 #4 내용). 6. **`src/tools/builtins/` 삭제**: `rm -rf src/tools/builtins` (이미 모두 옮겼는지 ls로 확인). 7. **tool-loop hoist**: `git mv src/skills/onboarding/runtime/tool-loop.ts src/agent/runtime/tool-loop.ts` (test도). trace 의존성을 `onToolCallStart` 콜백으로 일반화. 8. **`src/skills/onboarding/runtime/orchestrator.ts` 갱신**: `runWithTools` import 경로를 `@agent/runtime/tool-loop`로 변경, `onToolCallStart` 콜백으로 trace 주입. 9. **`src/skills/skill.ts` 인터페이스 확장**: `tools: readonly Tool[]` 추가. 10. **`src/skills/onboarding/skill.ts` 갱신**: - `@tools/builtins/index` import 제거. - 개별 tool import 추가. - `this.tools = onboardingToolList`. - `selectToolsForDerived`를 객체 참조로 재작성. - `ToolContext` 사용처를 `OnboardingToolContext`로 교체. - `tools` getter 노출. 11. **`src/skills/onboarding/index.ts`에 factory 추가** (위 #9 내용). 12. **`src/main.ts` 갱신** (위 #10 내용). 13. **`src/eval/judges/process-judge.ts` import 경로 갱신** (위 #11 내용). 14. **`docs/skill-authoring.md` 작성** (위 #14 내용). 15. **검증**: ```bash grep -rn "@tools/builtins" src # 0건 grep -rn "tool.name ===" src/skills # 0건 npm run typecheck npm run lint npm run test ``` 셋 다 통과하면 완료. --- ## 위험 요소 및 대응 | 위험 | 대응 | |---|---| | `Tool`의 default generic이 `ToolContext`라서 기존 호출부가 `OnboardingToolContext` 필드(`session`)를 못 읽을 수 있음 | onboarding 안의 모든 사용처를 `Tool<..., OnboardingToolContext>`로 명시적 선언. tool-loop는 generic하게 받으므로 무관. | | `selectToolsForDerived`가 `readonly Tool[]`를 반환하는데 `generateLlmText` 옵션이 `Tool[]`를 받으면 covariance 문제 발생 가능 | `generateLlmText`/`orchestrator.run`/`runWithTools`까지 일관되게 `OnboardingToolContext`로 흘려준다. tool-loop는 `Tool` generic으로 받도록 수정. | | trace 호출을 콜백으로 빼면서 누락이 생길 수 있음 | `tool-loop.test.ts`에 "콜백이 ok=true/false 둘 다에서 호출되는지" 테스트 한두 개 추가. | | `eval/runner.ts`의 `new OnboardingSkill(...)`가 ctor 시그니처 의존 | ctor는 건드리지 않으므로 회귀 없음. | | import 깊이가 한 단계 늘어나는 케이스 (`../../../config.js`) | 그대로 두거나, 필요하면 `@config` alias 신설. 본 plan에선 alias 추가 안 함. | | pre-commit hook이 lint/format을 강제할 수 있음 | 마지막에 `npm run lint:fix && npm run format` 한 번 실행. | --- ## 비목표 (이번 PR에서 안 함) - `src/skills/onboarding/runtime/orchestrator.ts`의 onboarding-specific planner를 generic화하는 작업 (별도 작업) - `prompts/tool-policy.ts`의 자연어 정책을 코드 정책으로 통합 (별도) - 두 번째 skill 추가 - `ToolRegistry` API 단순화 (`pick(names)` 제거 등) --- ## 검증 체크리스트 - [ ] `grep -rn "@tools/builtins" src` → 0건 - [ ] `grep -rn "from \"@skills/onboarding" src/skills/onboarding/tools` → 0건 (relative만) - [ ] `grep -n "tool.name ===" src/skills/onboarding/skill.ts` → 0건 - [ ] `npm run typecheck` 통과 - [ ] `npm run lint` 통과 - [ ] `npm run test` 통과 (특히 `tool-loop.test.ts`, `check-onboarding-progress.test.ts`, `verify-discord-nickname.test.ts`) - [ ] `npm run build` 통과 - [ ] `docs/skill-authoring.md` 존재