22 KiB
Refactor: agent / skills / tools DX 개선 plan
한 번의 작업 세션으로 codex가 처음부터 끝까지 수행할 수 있도록 작성된 단일 PR plan.
목표
지금 구조는 컨셉상 "agent ⊃ skills ⊃ tools"인데 실제 코드가 다음과 같이 어긋나 있다.
src/tools/builtins/의 5개 tool은 전부 onboarding 전용인데도 글로벌 폴더에 위치- tool 파일이
@skills/onboarding/*을 import (의존 방향이 거꾸로) OnboardingSkill이 모든 tool을createBuiltInToolRegistry().list()로 받아selectToolsForDerived()에서 이름 문자열로 필터 → 오타에 무방비runtime/tool-loop.ts는 generic LLM↔tool loop인데 onboarding 폴더 안에 갇혀 있음Skill인터페이스가name/canHandle/handle3줄뿐 — 새 skill이 어떻게 자기 tool을 선언할지 가이드 없음- 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
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<NatsClient, "request"> | undefined;
userId?: string | undefined;
session?: OnboardingSession | null | undefined;
garnetClient?: GarnetClient | undefined;
roomContextService?: RoomContextService | undefined;
}
export interface Tool<A, R> {
name: string;
description: string;
argsSchema: ZodType<A>;
resultSchema: ZodType<R>;
execute(args: A, ctx: ToolContext): Promise<R>;
}
after
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<NatsClient, "request"> | undefined;
userId?: string | undefined;
garnetClient?: GarnetClient | undefined;
roomContextService?: RoomContextService | undefined;
}
export interface Tool<A, R, C extends ToolContext = ToolContext> {
name: string;
description: string;
argsSchema: ZodType<A>;
resultSchema: ZodType<R>;
execute(args: A, ctx: C): Promise<R>;
}
@skills/onboarding/types import 한 줄과 session 필드 한 줄을 삭제, Tool에 generic C 추가. default를 ToolContext로 두면 기존 Tool<A, R> 호출도 그대로 유효.
2. src/skills/onboarding/tools/context.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<Args, Result> → Tool<Args, Result, OnboardingToolContext>로 변경. ctx 파라미터를 사용하는 함수(persistDiscordMemberId(memberId, ctx) 등) 내부 타입도 맞춰서 OnboardingToolContext로 갱신.
4. src/skills/onboarding/tools/index.ts — 신규 (구 tools/builtins/index.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<unknown, unknown, OnboardingToolContext>[] = [
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/ 폴더 삭제
rm -rf src/tools/builtins
6. src/skills/onboarding/skill.ts — tool 객체 직접 참조
다음 import를 추가:
import {
checkOnboardingProgressTool,
lookupCommunityRuleTool,
onboardingToolList,
validateNicknameTool,
verifyDiscordNicknameTool,
type OnboardingToolContext,
} from './tools/index.js';
기존:
import { createBuiltInToolRegistry } from '@tools/builtins/index';
import type { Tool, ToolContext } from '@tools/tool';
→ 다음으로 변경:
import type { Tool } from '@tools/tool';
(ToolContext 사용처는 모두 OnboardingToolContext로 교체)
생성자 내부:
this.tools = createBuiltInToolRegistry().list();
→
this.tools = onboardingToolList;
tools 필드 타입을 readonly Tool<unknown, unknown, OnboardingToolContext>[]로 변경.
buildToolContext(...) 반환 타입을 ToolContext → OnboardingToolContext.
generateLlmText 시그니처 옵션의 toolContext?: ToolContext | undefined → OnboardingToolContext | undefined. tools?: readonly Tool<unknown, unknown>[] | undefined → readonly Tool<unknown, unknown, OnboardingToolContext>[] | undefined.
핵심: selectToolsForDerived를 객체 참조로 다시 작성:
private selectToolsForDerived(
derived: DerivedState,
): readonly Tool<unknown, unknown, OnboardingToolContext>[] {
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 필드를 노출:
get tools(): readonly Tool<unknown, unknown>[] {
return onboardingToolList as readonly Tool<unknown, unknown>[];
}
(또는 그냥 public 필드로 두어도 됨. 테스트 깨지지 않게 getter 권장.)
7. src/skills/skill.ts — 인터페이스에 tools 추가
import type { AgentRequest, AgentResponse, ConversationMessage } from "@agent/types";
import type { Tool } from "@tools/tool";
export interface Skill {
readonly name: string;
readonly tools: readonly Tool<unknown, unknown>[];
canHandle(request: AgentRequest): boolean;
handle(
request: AgentRequest,
conversationHistory: ConversationMessage[],
): Promise<AgentResponse>;
}
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 변경:
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 콜백을 주입:
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에서:
import { runWithTools } from "./tool-loop.js";
→
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):
export { OnboardingSkill } from './skill.js';
export type { OnboardingSession } from './types.js';
추가:
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<NatsClient, 'request'>;
}
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:
const agent = new Agent(natsClient, conversationStore);
const shadowEvalBus = new ShadowEvalBus(garnetClient);
const onboardingSkill = new OnboardingSkill(
garnetClient,
llmClient,
roomContextService,
shadowEvalBus,
natsClient,
);
agent.registerSkill(onboardingSkill);
→
const agent = new Agent(natsClient, conversationStore);
const shadowEvalBus = new ShadowEvalBus(garnetClient);
const onboardingSkill = createOnboardingSkill({
garnetClient,
llmClient,
roomContextService,
shadowEvalPublisher: shadowEvalBus,
natsClient,
});
agent.registerSkill(onboardingSkill);
import 변경:
import { OnboardingSkill } from '@skills/onboarding/index';
→
import { createOnboardingSkill } from '@skills/onboarding/index';
11. src/eval/judges/process-judge.ts — registry import 경로 갱신
import { createBuiltInToolRegistry } from "@tools/builtins/index";
→
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 === '...'형태의 문자열 매칭 (객체 참조로 교체)
검증 명령:
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 — 신규 가이드
# Skill / Tool 추가 가이드
## 새 tool 추가
1. `src/skills/<your-skill>/tools/<tool-name>.ts` 생성.
2. `Tool<Args, Result, YourSkillToolContext>` 형태로 export.
3. `src/skills/<your-skill>/tools/index.ts`의 `onboardingToolList` 같은 배열에 등록.
4. skill 파일에서 직접 import해 `selectToolsForDerived`(또는 동등한 메서드)에 객체로 추가.
5. tool은 절대 `@skills/...` alias로 다른 skill을 import하지 않는다 (relative import만 허용).
## 새 skill 추가
1. `src/skills/<your-skill>/` 폴더 생성.
2. `Skill` 인터페이스(`src/skills/skill.ts`) 구현 — 최소한 `name`, `tools`, `canHandle`, `handle`.
3. `tools/` 서브폴더에 자기 tool 모음과 `<YourSkill>ToolContext extends ToolContext`.
4. `index.ts`에 `create<YourSkill>Skill(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를 돌릴 수 있다 (선택).
src/tools/tool.ts수정:OnboardingSessionimport 제거,session필드 제거,Tool에 genericC extends ToolContext = ToolContext추가.- 새 폴더 생성:
src/skills/onboarding/tools/,src/agent/runtime/. src/skills/onboarding/tools/context.ts작성 (위 #2 내용).- tool 5개 + test 2개 이동 (
git mv로). 각 파일 import 경로 갱신 + 시그니처Tool<A, R, OnboardingToolContext>로 변경. src/skills/onboarding/tools/index.ts작성 (위 #4 내용).src/tools/builtins/삭제:rm -rf src/tools/builtins(이미 모두 옮겼는지 ls로 확인).- tool-loop hoist:
git mv src/skills/onboarding/runtime/tool-loop.ts src/agent/runtime/tool-loop.ts(test도). trace 의존성을onToolCallStart콜백으로 일반화. src/skills/onboarding/runtime/orchestrator.ts갱신:runWithToolsimport 경로를@agent/runtime/tool-loop로 변경,onToolCallStart콜백으로 trace 주입.src/skills/skill.ts인터페이스 확장:tools: readonly Tool[]추가.src/skills/onboarding/skill.ts갱신:@tools/builtins/indeximport 제거.- 개별 tool import 추가.
this.tools = onboardingToolList.selectToolsForDerived를 객체 참조로 재작성.ToolContext사용처를OnboardingToolContext로 교체.toolsgetter 노출.
src/skills/onboarding/index.ts에 factory 추가 (위 #9 내용).src/main.ts갱신 (위 #10 내용).src/eval/judges/process-judge.tsimport 경로 갱신 (위 #11 내용).docs/skill-authoring.md작성 (위 #14 내용).- 검증:
셋 다 통과하면 완료.
grep -rn "@tools/builtins" src # 0건 grep -rn "tool.name ===" src/skills # 0건 npm run typecheck npm run lint npm run test
위험 요소 및 대응
| 위험 | 대응 |
|---|---|
Tool<A, R>의 default generic이 ToolContext라서 기존 호출부가 OnboardingToolContext 필드(session)를 못 읽을 수 있음 |
onboarding 안의 모든 사용처를 Tool<..., OnboardingToolContext>로 명시적 선언. tool-loop는 generic하게 받으므로 무관. |
selectToolsForDerived가 readonly Tool<unknown, unknown, OnboardingToolContext>[]를 반환하는데 generateLlmText 옵션이 Tool<unknown, unknown>[]를 받으면 covariance 문제 발생 가능 |
generateLlmText/orchestrator.run/runWithTools까지 일관되게 OnboardingToolContext로 흘려준다. tool-loop는 Tool<unknown, unknown, C> 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 추가
ToolRegistryAPI 단순화 (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존재