Kiro Migration Guide

You can migrate a Kiro repository to Claude Code without rewriting the application or throwing away its specifications. The durable assets are Markdown and source code. The parts that need translation are when instructions load, when automation fires, and where each tool stores configuration.

The safest migration is boring: copy first, map one subsystem at a time, and keep Kiro working until Claude Code passes the same tests.

The migration map

Kiro and Claude Code have similar building blocks with different names and loading rules. The Kiro comparison covers the product decision. This guide handles the repository work after you decide to move.

Kiro's current steering documentation defines four inclusion modes: always, file match, manual, and automatic. Claude Code splits those jobs across CLAUDE.md, rules, and skills. Treating every steering file as always-on context would technically work, but it would waste context and weaken the useful instructions.

Final file tree

This example starts with Kiro's three foundation documents and one checkout spec. The migrated repository keeps the old .kiro directory until verification is complete.

your-app/
├── .claude/
│   ├── rules/
│   │   ├── product.md
│   │   ├── tech.md
│   │   ├── structure.md
│   │   └── react-components.md
│   ├── skills/
│   │   └── release-check/
│   │       └── SKILL.md
│   ├── hooks/
│   │   └── format-edited-file.mjs
│   └── settings.json
├── .kiro/
│   ├── hooks/
│   ├── specs/
│   └── steering/
├── docs/
│   └── specs/
│       └── checkout/
│           ├── requirements.md
│           ├── design.md
│           └── tasks.md
├── CLAUDE.md
└── package.json

Make a reversible copy

Do not delete .kiro during the first pass. A migration that changes source code and configuration at the same time is hard to debug because you cannot tell whether the agent changed behavior or the app broke.

Create a branch, record the current checks, and copy the specs. The commands stop on failure and never overwrite the Kiro source files.

set -euo pipefail

git switch -c chore/migrate-kiro-to-claude
mkdir -p .claude/rules .claude/skills docs/specs

if [ -d .kiro/specs ]; then
  cp -R .kiro/specs/. docs/specs/
fi

npm run typecheck
npm run lint
npm run build

If your project uses different commands, run the ones already documented in package.json. Save the output from this baseline. The same checks must pass after the migration.

Move always-on steering

Kiro can generate product.md, tech.md, and structure.md in .kiro/steering. Its official docs say those files describe the product, stack, and repository structure, and load by default.

Claude Code can load repository instructions from CLAUDE.md and .claude/rules/. Keep the root file short. Use it as a map and put the detailed material in focused rule files.

# Project instructions

Read the focused rules in `.claude/rules/` before changing the related area.

## Commands

- Type check: `npm run typecheck`
- Lint: `npm run lint`
- Test: `npm test`
- Production build: `npm run build`

## Working agreement

- Inspect existing patterns before creating a new abstraction.
- Plan database or authentication changes before editing.
- Run the smallest relevant test during implementation.
- Run all four quality commands before declaring the task complete.

Copy the body of Kiro's three foundation files into .claude/rules/product.md, .claude/rules/tech.md, and .claude/rules/structure.md. Remove Kiro-only inclusion frontmatter. Do not merge the three into one giant root file.

The Claude Code memory guide explains why this split matters. Root instructions load at session start, while more specific instructions can load when Claude reaches the relevant part of the repository.

Translate file-matched steering

Kiro uses inclusion: fileMatch and fileMatchPattern to load a steering file for matching paths. Claude Code rules use a paths list for the same broad goal.

Suppose the Kiro file looked like this. It applies only while Kiro works on React components.

---
inclusion: fileMatch
fileMatchPattern: "components/**/*.tsx"
---

# React component rules

- Use Server Components by default.
- Add `"use client"` only for browser APIs, state, or event handlers.
- Keep data access outside presentational components.
- Use existing shadcn/ui primitives before adding a new component.

Create .claude/rules/react-components.md with Claude Code's path frontmatter. The instruction body stays plain Markdown.

---
paths:
  - "components/**/*.tsx"
  - "app/**/*.tsx"
---

# React component rules

- Use Server Components by default.
- Add `"use client"` only for browser APIs, state, or event handlers.
- Keep data access outside presentational components.
- Use existing shadcn/ui primitives before adding a new component.

Review the patterns instead of copying them blindly. A Kiro pattern anchored to components/ may miss Next.js files under app/, and a broad TypeScript pattern may load frontend rules into database migrations.

Turn manual steering into a skill

Manual Kiro steering loads when you explicitly reference it. Automatic steering loads when Kiro judges its name and description relevant. Claude Code skills cover both of those use cases more naturally than an always-loaded rule.

This complete skill creates a reusable release checklist. Save it as .claude/skills/release-check/SKILL.md.

---
name: release-check
description: Verify a release candidate before deployment. Use for release checks, production deploys, and launch readiness.
---

# Release check

1. Read the changed files and summarize the user-visible impact.
2. Run the repository type check, lint, test, and production build commands.
3. Check that new environment variables appear in `.env.example`.
4. Check database migrations for a rollback path.
5. Report failures with the exact command and relevant output.
6. Do not deploy or push. Return a release verdict for human approval.

The description does real work. Claude uses it to decide when the skill applies, so name the requests a builder would actually type. Avoid descriptions such as "helps with releases" that provide no trigger signal.

Keep Kiro specs intact

Kiro specs are already useful Markdown. The current Kiro specs reference defines requirements.md, design.md, and tasks.md, with requirements, architecture, and discrete implementation work respectively.

Keep those files together. Tell Claude exactly how they control implementation instead of asking it to infer the relationship.

# Checkout feature

The source documents for this feature are:

- `docs/specs/checkout/requirements.md`
- `docs/specs/checkout/design.md`
- `docs/specs/checkout/tasks.md`

Before implementation:

1. Check requirements for ambiguous acceptance criteria.
2. Check the design against the current repository.
3. Identify incomplete tasks and their dependencies.
4. Propose a build plan.

During implementation, update task status only after its acceptance criteria pass.
Do not rewrite product requirements to match an implementation shortcut.

You can place this instruction beside the spec or turn it into a project skill. The spec-driven development guide explains the deeper workflow. The migration rule is simple: preserve requirements as the source of truth rather than collapsing everything into one prompt.

Rebuild hooks by behavior

Kiro and Claude Code both have hooks, but the event models are not identical. Kiro supports editor events such as file save. Claude Code's PostToolUse event fires after Claude's Edit or Write tool succeeds.

That difference means a file-save hook is not a direct copy. The following script reads Claude Code's hook event from standard input, validates that the edited file belongs to the repository, and runs the project's Prettier installation on that one file.

Save it as .claude/hooks/format-edited-file.mjs. It does not format files a human saves in the editor.

import { spawnSync } from "node:child_process";
import { resolve, relative } from "node:path";

let input = "";

for await (const chunk of process.stdin) {
  input += chunk;
}

const event = JSON.parse(input);
const projectDir = resolve(event.cwd || process.cwd());
const requestedPath = event.tool_input?.file_path;

if (typeof requestedPath !== "string") {
  process.exit(0);
}

const filePath = resolve(projectDir, requestedPath);
const pathFromProject = relative(projectDir, filePath);
const isOutsideProject =
  pathFromProject === ".." ||
  pathFromProject.startsWith("../") ||
  pathFromProject.startsWith("..\\");

if (isOutsideProject) {
  console.error(`Refusing to format a file outside the project: ${filePath}`);
  process.exit(1);
}

const result = spawnSync(
  "npx",
  ["prettier", "--write", filePath],
  {
    cwd: projectDir,
    encoding: "utf8",
    shell: false,
  },
);

if (result.stdout) {
  process.stderr.write(result.stdout);
}

if (result.stderr) {
  process.stderr.write(result.stderr);
}

process.exit(result.status ?? 1);

Register that script in the project settings. The matcher keeps it limited to successful file writes by Claude.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/format-edited-file.mjs\"",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Hook inputs evolve. Compare the event fields with Anthropic's current hooks guide and test the script on a disposable file. If the repository already formats through lint-staged or the editor, you may not need this hook at all.

Migrate one hook at a time:

1. Write down the behavior and why it exists.
2. Find the closest Claude Code event.
3. Check the current event input schema.
4. Run it against a harmless fixture.
5. Confirm its failure behavior.
6. Remove the Kiro hook only after parity.

Be especially careful with hooks that deploy, delete, or call an external API. A familiar filename does not make an incompatible event safe.

Re-register MCP servers

MCP is the most portable part conceptually and the least portable as a raw config file. Both products support local and remote MCP servers, but config paths, scope, authentication, and approval settings can differ.

List the Kiro servers first, then add each one through Claude Code's current MCP command or project configuration. Test a read-only tool before granting write access.

claude mcp list
claude mcp add --transport stdio filesystem -- \
  npx -y @modelcontextprotocol/server-filesystem .
claude mcp list

The filesystem server above can read the directory you pass to it. Use a narrower directory than . when the server does not need the whole repository. Never move API keys from a committed Kiro file into another committed file.

Verify the migration

Start a fresh Claude Code session so it discovers the new files. Ask it to state which instructions loaded, then give it one small task covered by an existing Kiro spec.

Read docs/specs/checkout/requirements.md, design.md, and tasks.md.
Do not edit yet.
Report the next incomplete task, its dependencies, the project rules that apply,
and the exact checks you will run after implementation.

Compare that plan with what Kiro produced. You are looking for missing constraints, not identical wording.

After the small task, run the same baseline commands from the migration branch:

set -euo pipefail

npm run typecheck
npm run lint
npm test
npm run build
git diff --check
git status --short

Keep .kiro for a few real tasks. Once the new workflow consistently loads the right instructions, respects specs, runs hooks, and reaches the same quality gates, remove the old configuration in a separate commit. That separation makes rollback obvious.

Frequently asked questions

Can I migrate a Kiro project to Claude Code?

Yes. Source code and spec Markdown need no conversion. Persistent instructions, conditional loading, hooks, and MCP registration need explicit mapping and testing.

What replaces Kiro steering in Claude Code?

Use CLAUDE.md for short repository-wide instructions, .claude/rules/ for focused or path-scoped rules, and .claude/skills/ for workflows that should load on demand.

Do Kiro hooks work unchanged in Claude Code?

No. Recreate the intended behavior against Claude Code's current event and input schema. Test every migrated hook before deleting its Kiro version, especially hooks with external side effects.

The $29 Code Kit is a one-time Claude Code harness for builders who want the planning, build handoffs, evaluation, browser and API testing, and quality gates already wired together. It requires a paid Anthropic plan for Claude Code, and it does not replace that plan. The value is the maintained pipeline, not pretending two configuration formats are interchangeable.

Posted by @speedy_devv