This commit is contained in:
dahyeon committed 2026-05-12 08:16:31 -07:00
1 parent 1453433b62
commit da76af3826
65 files changed
+11089 -143

No files matched your search

+621
View File
@@ -0,0 +1,621 @@
# 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<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**
```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<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` — 신규 파일
```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` 대체)
```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/` 폴더 삭제
```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<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`를 객체 참조로 다시 작성:
```ts
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` 필드를 노출:
```ts
get tools(): readonly Tool<unknown, unknown>[] {
return onboardingToolList as readonly Tool<unknown, unknown>[];
}
```
(또는 그냥 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<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` 변경:
```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<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`:
```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/<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. **검증**:
```bash
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` 존재