Files
lolympus-agent/docs/refactor-skills-tools-plan.md
T
2026-05-12 08:16:31 -07:00

22 KiB

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

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를 돌릴 수 있다 (선택).

  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<A, R, OnboardingToolContext>로 변경.
  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. 검증:
    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 추가
  • 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 존재