keryx: Skill for Claude Code

Refactoring Workflow

Refactoring means changing code structure without changing behavior. Every step must preserve the existing test suite and public API contracts.

Phase 1: Understand Before Touching

1. Read the target code — understand what it does, who calls it, and what depends on it
2. Check for tests — find existing test coverage for the code being refactored
   • Search in packages/keryx/__tests__/ for framework code
   • Search in example/backend/__tests__/ for app code
3. Run the existing tests to establish a green baseline before making changes:

   cd packages/keryx && bun test        # framework code
   cd example/backend && bun test       # app code
   

4. Check for stale processes if tests behave unexpectedly:

   ps aux | grep "bun keryx" | grep -v grep
   

Phase 2: Plan the Refactoring

Before writing code, state the plan concisely:

• What structural change you're making and why it improves the code
• Which files will be created, modified, or deleted
• Any import paths that will change
• Whether the public API surface changes (it shouldn't)

If the refactoring is large (touches more than 5 files), break it into incremental steps where tests pass after each step.

Phase 3: Make Changes

Apply changes incrementally. After each logical step, verify nothing broke.

Import Conventions (must follow)

• In packages/keryx/ — use relative imports:

  import { api } from "../api";
  import { Action } from "../classes/Action";
  

• In example/backend/ — use "keryx" for framework, relative for app-local:

  import { api, Action, type ActionParams, HTTP_METHOD } from "keryx";
  import { SessionMiddleware } from "../middleware/session";
  

Code Quality Rules

• No as any — use @ts-expect-error with a comment if the type system can't express something
• JSDoc annotations on any new or modified public APIs in packages/keryx/
• Don't add unnecessary abstractions — three similar lines are better than a premature helper
• Don't add comments, docstrings, or type annotations to code you didn't change
• If something is unused after the refactor, delete it completely — no _unused renames or // removed comments