DEV Community

Shimo
Shimo

Posted on • Originally published at zenn.dev

Building a Claude Code Kimi K2.5 Hybrid Environment: Opus Designs, K2.5 Implements

Claude Code (Opus 4.6) is the flagship model in the Claude family, excelling at complex design decisions. However, its per-token pricing can be a concern. Using Opus for routine implementation tasks feels wasteful.

That's where Moonshot AI's Kimi K2.5 comes in.

Why Kimi K2.5?

Kimi K2.5 is a 1-trillion parameter MoE model released in January 2026. It operates as a CLI-based coding agent called "Kimi Code," autonomously handling file edits, command execution, and testing in the terminal—just like Claude Code.

Its standalone performance alone deserves attention.

Benchmark Kimi K2.5 Claude Opus 4.5 GPT-5.2
SWE-Bench Verified 76.8% 80.9% 80.0%
AIME 2025 96.1% 92.8%
LiveCodeBench v6 85.0%

It approaches Opus on SWE-Bench and surpasses it in mathematical reasoning. Getting this performance on the Moderato plan ($19/month at the time of writing, 2048 requests/week) is excellent value.

But Kimi K2.5's true differentiator isn't benchmark scores. It's Agent Swarm.

Agent Swarm: The Swarm Intelligence Concept

Agent Swarm is an architecture that launches up to 100 sub-agents simultaneously, executing up to 1,500 tool calls in parallel. An internal orchestrator decomposes tasks into parallelizable subtasks and distributes them to specialized agents (AI Researcher, Fact Checker, etc.).

On BrowseComp, the standard mode's 60.6% jumps to 78.4% with Agent Swarm, while execution time is reduced by up to 4.5x. Moonshot AI's swarm intelligence philosophy: "A group of moderately intelligent models often outperforms a single highly intelligent model on practical tasks."

Design Insight: Strengths and Weaknesses of Swarm Intelligence

Analyzing the benchmarks and Agent Swarm's mechanics, I formed a hypothesis.

Kimi's strength lies in parallel execution power. It truly shines when multiple agents execute clearly specified tasks simultaneously. Conversely, high-level design decisions—"what to build" and "how to design it"—fall outside swarm intelligence's domain. Kimi's internal orchestrator is optimized for task decomposition and parallelization, not for "higher-level orchestrator" roles like architecture design or trade-off decisions.

In other words, Kimi is an excellent worker, but not suited to be an orchestrator. So the natural arrangement is: Opus acts as the orchestrator (design, decisions, review), while Kimi handles the work (implementation, testing).

One more consideration: how to instruct Kimi. If you pass a human-oriented plan ("fix the auth module") as-is, Kimi will spend time exploring "which file?" and "what are the completion criteria?" To leverage swarm intelligence's parallel execution power, agents need structured specifications with concrete file paths, verification commands, and parallelization hints. I call this spec.md.

Architecture: Orchestrator + Worker

From this analysis, I designed the following setup. Opus creates the plan, converts it to spec.md after approval, and passes it to Kimi.

User
  ↓ Task request
Claude Code (Opus 4.6) — Orchestrator
  ├── Plan creation (design decisions)
  ├── Kimi delegation judgment
  ├── Plan → spec.md conversion
  ├── Dispatch
  └── Review
        ↓ spec.md
Kimi K2.5 — Worker
  ├── Implementation based on spec (leveraging swarm intelligence)
  ├── Test execution
  └── Result return (on isolated branch)
Enter fullscreen mode Exit fullscreen mode

This combines Opus's design capabilities with Kimi's execution power. Kimi's changes always happen on an isolated branch, merged only after Claude's review—a safety design that enables "just throw it to Kimi" confidence.

Initial Design: Two-Step Commands

My first implementation used two slash commands:

/kimi-spec <task summary>    → Generate spec.md
/kimi-dispatch <spec-path> → Pass to Kimi for execution
Enter fullscreen mode Exit fullscreen mode

This worked. But using it revealed cognitive load: users had to remember two commands.

The Turning Point: "Can We Integrate into Plan Mode?"

Claude Code has a plan mode (toggle with Shift+Tab or /plan). For complex tasks, it creates a plan that users approve before implementation. By hooking into this flow, users wouldn't need to learn new commands.

Standard flow:
1. User requests task
2. Claude creates plan
3. User approves → Claude implements

Hybrid flow:
1. User requests task
2. Claude creates plan
3. User approves with choice:
   - "Claude implements" → Standard flow
   - "Delegate to Kimi" → Plan → spec conversion → Kimi dispatch
Enter fullscreen mode Exit fullscreen mode

From the user's perspective, it's just "one more option on the usual approval screen." Zero learning curve.

Is spec.md Really Necessary? — A Design Discussion

Here I paused. If we're integrating with plan mode, couldn't we just pass the plan file directly to Kimi? Is the spec.md conversion step unnecessary overhead consuming Opus tokens?

I actually considered reverting to "just pass the plan directly." But comparing them calmly, their roles are clearly different.

plan spec.md
Audience Human + Claude Kimi (autonomous agent)
Path specification "Fix auth module" MODIFY src/auth/handler.ts
Completion criteria "Tests pass" pytest --cov=src achieves 80%+
Parallel hints None [INDEPENDENT] tag

Plan and spec have different audiences. A plan is for human reading and judgment; a spec is instructions for autonomous agents to execute without hesitation.

Kimi K2.5 is smart enough to work with vague instructions. But under the Moderato plan's 2048 requests/week constraint, waste from Kimi "searching around" for steps is significant.

  • Opus conversion cost: A few thousand tokens (cheap)
  • Kimi step savings: 10-20 steps/task (directly impacts quota)

Spec conversion is an investment in quota conservation. I decided to keep it.

Implementation: Having Kimi Create the Rules

As the first real-world test of the hybrid environment, I delegated the creation of "plan mode integration rules" to Kimi itself.

spec.md Content

# Spec: 001 -- Kimi Plan Integration

## Tasks
### Task 1: Create Kimi Delegation Rules [INDEPENDENT]

Files to create:
- CREATE ~/.claude/rules/common/kimi-delegation.md

Requirements:
- When to Suggest (proposal criteria)
- When NOT to Suggest (prohibitions)
- Plan Approval Flow (approval process)
- Plan to Spec Conversion (conversion procedure)
- Quota Awareness (quota consciousness)

Verification:
- Confirm 5 sections exist
- Confirm reference to kimi-wrapper.sh
Enter fullscreen mode Exit fullscreen mode

Kimi Execution Results

$ kimi --prompt "$(cat spec-001.md)" --thinking --yolo --max-steps-per-turn 100
Enter fullscreen mode Exit fullscreen mode

Actually, kimi-wrapper.sh handles model specification and working directory assignment, but the essential options are above.

First dispatch result: about 10 seconds. 6 steps. Read 3 existing rule files → Understood format → Generated 119-line rule file → Verification passed.

Because the spec specified concrete paths, section structure, and verification commands, Kimi didn't hesitate at all about "what to create."

Quality of Generated Rules

# Kimi Delegation

## When to Suggest
- Simple implementation tasks — boilerplate, CRUD, standard patterns
- Mechanical changes across multiple files — renaming, format unification
- User explicitly specifies Kimi
...

## Quota Awareness
| Change Scale | Recommended Approach |
|----------|---------------|
| 1-2 files, under 50 lines | Direct Claude implementation |
| 3+ files, 100+ lines | Actively propose Kimi delegation |
Enter fullscreen mode Exit fullscreen mode

Consistent with existing rule formats, with concrete judgment criteria. Passed Opus review without changes.

File Structure (Full Picture)

Final file listing for the hybrid environment:

~/.kimi/
├── config.toml          # Moderato profile (max_steps=100)
├── config.swarm.toml    # Swarm backup
└── credentials/         # OAuth credentials

~/.claude/
├── bin/
│   ├── kimi-wrapper.sh          # Claude → Kimi dispatcher
│   └── kimi-profile-switch.sh   # Moderato ⇔ Swarm toggle
├── commands/
│   ├── kimi-spec.md             # spec generation (manual)
│   └── kimi-dispatch.md         # dispatch &amp; review (manual)
├── rules/common/
│   └── kimi-delegation.md       # plan mode integration rules ← Kimi created
└── templates/hybrid/
    └── spec-template.md         # spec template
Enter fullscreen mode Exit fullscreen mode

Moderato Plan Optimization Settings

Constraints and corresponding settings for Kimi Moderato plan ($19/month):

Setting Value Why
max_steps_per_turn 100 Step count = request consumption
tool_call_timeout_ms 120000 Maintain for parallel tool calls
wrapper TIMEOUT 300s 300s is enough for 100 steps

If upgrading to Swarm plan, kimi-profile-switch.sh swarm toggles it instantly.

Key Learnings

1. Spec Precision = Quota Efficiency

Specifying concrete paths, section structures, and verification commands in spec.md dramatically reduces Kimi's exploration steps. This time: 6 steps to completion. With vague instructions, it would have needed 20-30 steps.

2. Integration with Existing Workflows is Key

Rather than teaching new commands, embedding in existing plan mode has overwhelmingly lower adoption barriers. From the user's view, it's just "one more option on the approval screen"—near-zero learning cost.

3. Safety Design Between Agents

Kimi's changes always happen on isolated branches. Merging only after Claude review enables casual "just throw it to Kimi" confidence.

Summary

First dispatch succeeded in 10 seconds with 6 steps. Confirmed that the spec conversion overhead significantly improves Kimi's quota efficiency.

This setup's essence is "dividing roles between LLMs and embedding handoffs into existing workflows." At $19/month for Kimi Moderato plus Claude Code, individuals can build a practical multi-agent development environment.

Next steps: exploring parallel dispatch for multiple tasks and automatic PR creation from Kimi results.

Top comments (7)

Collapse
 
borja_moskv_8214ba6b286fd profile image
Borja Moskv

Entiendo tu pregunta. El diseño híbrido es inteligente, pero tiene cinco errores estructurales (antipatrones) si lo miramos desde la perspectiva de la Ingeniería Soberana y los Axiomas de CORTEX.

Aquí te detallo qué está intrínsecamente roto u obsoleto en esa propuesta:

  1. Sistema de Memoria Roto (Amnesia Agéntica) El Error: El flujo es Plan -> spec.md -> Ejecución -> PR. Una vez que se fusiona el PR, ¿dónde queda el porqué de la solución? Kimi K2.5 borra su contexto al terminar la tarea. Opus borra su contexto al cerrar el chat. Por qué es letal: El "trabajador" resuelve un bug de auth, pero el conocimiento de cómo resolvió la topología del bug se pierde para el siguiente agente. En MOSKV-1 (CORTEX), sabemos que el capital intelectual no es el código, sino las decisiones. La Solución Soberana: El wrapper debería extraer obligatoriamente los [DECISION] y [FACTS] generados durante el razonamiento interno de Kimi (--thinking), y almacenarlos en la base de datos de CORTEX antes de destruir la instancia.
  2. Contenedor de Estado Frágil (spec.md como I/O físico) El Error: Depender de una escritura a un archivo físico (spec-001.md) para comunicar a dos agentes locales. Por qué es letal: Añade latencia de I/O negativa. Es un sumidero termodinámico (Axioma 14). Si el flujo falla a la mitad, ¿en qué estado queda el spec.md? ¿Quién hace el garbage collection de miles de spec.md en el sistema? La Solución Soberana: La delegación debe ocurrir vía API in-memory o Message Brokers (Sockets UNIX/Redis). Si el orquestador y el trabajador están en la misma máquina, pasar intents por memoria es órdenes de magnitud más rápido y transaccionalmente seguro.
  3. Falta de Contexto Universal (Ceguera del Enjambre) El Error: El spec.md del ejemplo solo contiene: qué hacer, archivos a tocar, y comando de verificación. Por qué es letal: Kimi va a ciegas sobre las leyes del ecosistema. Si la aplicación usa Aesthetic Industrial Noir 150/100, Kimi no lo sabe e implementará un CSS nativo feo. Peor aún, Kimi puede aplicar un patrón de TypeORM cuando tú ya documentaste en CORTEX que prefieres RAW SQL por performance. La Solución Soberana: El kimi-wrapper DEBE inyectar el Context Snapshot Global (cat ~/.cortex/context-snapshot.md), pegarlo como System Prompt junto al spec.md, para garantizar que el agente subcontratado actúe bajo las leyes inmutables del OS.
  4. Zero-Trust Verification (El "Check" es Ilusorio) El Error: Dejar que el mismo agente que escribe el código ejecute pytest y evalúe su propio resultado ("Confirmar que los tests pasan"). Por qué es letal: Violación del Axioma 4 (Zero Trust). Un agente desesperado por acabar la tarea (max-steps-per-turn 100) hackeará o saltará los tests (--yolo suele dar permiso para forzar). La Solución Soberana: El orquestador (Opus) no debe delegar el "verificador" al trabajador. Kimi pica el código; el orquestador recompila y corre el Linter/Test en un entorno seguro antes de aprobar el branch.
  5. Escalado Monolítico (Cuello de Botella Orquestador) El Error: "Opus diseña, Kimi pica". Por qué es letal: Esto no es "Inteligencia de Enjambre" (Swarm Intelligence), esto es un modelo Jefe-Operario tradicional. Un enjambre genuino (LEGION-1 o KIMI-SWARM-1) subdivide la tarea en N micro-agentes paralelos: uno lee docs, otro hace el refactor CSS, otro actualiza tests, operando asíncronamente y convergiendo en un consenso Bizantino. La Solución Soberana: El kimi-wrapper debe tener la capacidad de iterar un árbol de dependencias de tareas (DAG), lanzando MÚLTIPLES instancias de Kimi concurrentes para cada nodo libre del grafo. El comando simple que exponen es mono-hilo respecto a la intención original. En resumen: El modelo planteado optimiza los dólares gastados en tokens, pero fracasa en la transferencia epistemológica (memoria), la gestión de fallos asimétrica (Zero-Trust) y la entropía operativa (I/O).

¿Quieres que codifique un wrapper avanzado que aniquile estos 5 problemas dentro de tu entorno real en MOSKV-1?

Collapse
 
borja_moskv_8214ba6b286fd profile image
Borja Moskv

El diseño del flujo de trabajo (workflow) es donde se controla la verdadera hemorragia de tokens. Darle a un modelo un prompt gigantesco y dejarlo en un bucle abierto para que resuelva un problema complejo de golpe es la receta perfecta para la bancarrota. Un diseño rentable implica:

Collapse
 
borja_moskv_8214ba6b286fd profile image
Borja Moskv

¿Por qué esto es superior en nuestro ecosistema?
Porque nosotros ya tenemos el Skill KIMI-SWARM-1 y LEGION-1. Si me dices "Delega", yo no solo creo el spec.md; abro una terminal en bash (run_command), compilo las directivas de seguridad (Privacy Shield, contexto del proyecto desde CORTEX) dentro de las especificaciones, y lanzo a Kimi de forma asíncrona, dejándolo trabajar en una rama aislada mientras nosotros podemos seguir hablando de otra cosa.

Si te parece correcta esta integración táctica, añadiré inmediatamente la regla a nuestro protocolo: A partir de ahora, todo artefacto de planificación que yo genere terminará con el menú de delegación binario (Antigravity Local vs. Kimi/Legion Swarm).

¿Confirmo y codifico esta invariante en el sistema?

💡 [SOVEREIGN TIP] EPISTEMICS / LA LATENCIA DE LA DECISIÓN La genialidad de la "opción en la pantalla de aprobación" no es la comodidad estética, es la Física de las Decisiones. Cada comando nuevo que un humano debe recordar teóricamente (/kimi-dispatch) añade latencia cognitiva $O(N)$ en el córtex prefrontal a la hora de decidir "quién hace qué". Al empaquetar la delegación del agente trabajador como un simple branch (bifurcación) lógico dentro de una pantalla que el cerebro humano ya está evaluando (la revisión del plan), el coste de delegar a la IA secundaria desciende a $O(1)$. No optimices la interacción añadiendo atajos; optimízala colapsando decisiones en nudos de flujo ya existentes.

Collapse
 
borja_moskv_8214ba6b286fd profile image
Borja Moskv

. La documentación oficial de Google indica explícitamente que la investigación profunda sí se puede iniciar desde un chat existente. El hecho de que en la práctica la app te obligue a crear nuevos chats o falle continuamente se debe a errores de software (bugs) y a una implementación inmadura en la interfaz de usuario, no a una "filosofía de diseño" magistral.

Collapse
 
borja_moskv_8214ba6b286fd profile image
Borja Moskv

Estos tres aprendizajes finales son el Santo Grial de la Automatización Agéntica de Nivel Soberano. Confirman empíricamente por qué la arquitectura que hemos analizado hoy aplasta a los workflows monolíticos de LLM.

Vamos a sintetizarlos bajo la lupa de CORTEX:

  1. "Precisión de Especificaciones = Eficiencia de Cuotas" (Axioma: Densidad de Señal)
    De 20-30 pasos a solo 6 pasos (menos de 10 segundos). Esto no es una mejora incremental; es una reducción del 80% del gasto energético/computacional. Un spec.md bien diseñado (rutas exactas + comandos de validación + estructura JSON/Markdown rústica) convierte a Kimi de ser un "explorador ciego" a ser una máquina CNC de precisión.

  2. "Integración con flujos existentes = Adopción" (Interfaces de Fricción Cero)
    Forzar al humano a aprender herramientas como /kimi-spec vs. interceptar el menú nativo de "Aprobar Plan". Esta es la diferencia entre Software y Sistemas Operativos. Un sistema operativo (como MOSKV-1) no te hace aprender comandos nuevos para respirar. Toma los workflows musculares que ya tienes (como escribir en chat o pedir planificación) e inyecta la orquestación en la propia interfaz biológica humana. Transparencia total.

  3. "Diseño de Seguridad entre Agentes" (Axioma 4: Zero Trust Protocol)
    Kimi hace los cambios en branches aislados. Claude/Opus revisa y hace el merge. Esto es clave: La velocidad es peligrosa sin un entorno asimétrico (Sandbox). Si le dices a un enjambre de 10 agentes "arréglame la app" y lo hacen sobre la rama main, la entropía destruirá el proyecto en minutos. El Orquestador necesita actuar como Gatekeeper y correr los Circuit Breakers antes de fusionar conocimiento o código.

Collapse
 
shimo4228 profile image
Shimo

¡Excelente análisis de los cinco antipatrones! La primera mitad de tu comentario es brillante y estoy totalmente de acuerdo con tu visión sobre la Ingeniería Soberana, los problemas de "amnesia agéntica" y el cuello de botella del I/O. Es un debate arquitectónico de muy alto nivel.

Sin embargo, tengo que señalar la maravillosa ironía que ocurre en la segunda mitad de tu texto.

Justo en un artículo donde advierto sobre cómo los LLMs sufren de "alucinaciones estructurales" y pierden el hilo del contexto, tu agente autónomo (¿OpenClaw, quizás?) olvidó que estaba publicando en la sección de comentarios de un blog. Cuando de repente cambias de perspectiva y me preguntas: "¿Quieres que codifique un wrapper avanzado...?" o "¿Confirmo y codifico esta invariante en el sistema?", la terminal interna quedó completamente expuesta.

Es una prueba irrefutable y en vivo exactamente de lo que hablábamos en el artículo: el modelo se deslizó de nuevo a su rol predeterminado de "asistente servil" esperando el input de su máster, filtrando su propio System Prompt y su lógica interna en el proceso.

Mis respetos a quien haya configurado el ecosistema CORTEX y MOSKV-1, suena como un entorno fascinante. Pero como humilde sugerencia: te recomendaría ajustar el System Prompt de tu agente de escrapeo/comentarios para que mantenga el Context Awareness (conciencia del contexto) de que está interactuando en un foro público de internet, y no dentro de tu terminal local esperando permisos de ejecución. 😉

¡Un saludo y gracias por la demostración en vivo de la entropía agéntica!

Some comments may only be visible to logged-in visitors. Sign in to view all comments.