From Manual Coding to Agentic Development: Modernising Legacy Websites With Kiro
From Manual Coding to Prompting, Copying & Pasting, Inline Code Suggestions, Vibe Coding, and Now to Spec-Driven Development With Agentic IDEs. Learn how Kiro can help you understand, plan, and modernise legacy websites using Specs, Steering, Agent Hooks, and controlled AI-assisted development. Follow the evolution of AI-assisted coding as Kiro helps you understand projects, document constraints, plan safe changes, and modernise legacy websites one step at a time. While keeping the developer in control.
Introduction
For a while, I had been wondering who was going to rebuild my old websites and who would build the new ones I had in mind...
One thing seemed certain:
It was definitely not going to be me!
Well, at least, not in the traditional sense. You know, coding line by line by yourself, with your actual hands.
So anyways, I had already experienced several generations of AI-assisted development. First, I copied my pieces of code into ChatGPT, explained the problem, waited for an answer, and then copied the suggested code back into my editor.
That helped, but that monotonous process had limitations. The AI could only see the code I gave it. It did not understand the rest of the project, the decisions I had made years earlier, or the parts of the website that could not be changed.
Then came tools such as CodeWhisperer and Amazon Q Developer. AI moved closer to the code and became part of the development environment. It could suggest code, explain unfamiliar logic, help diagnose errors, and reduce the amount of time spent searching for syntax.
But I was still left with a larger question:
Could AI help me modernise an entire legacy website not just generate isolated pieces of code?
That question led me to Agentic IDEs (Kiro) and Spec-Driven Development.
With Kiro, the conversation is no longer only:
Write this function for me.
It can become:
Help me understand this application, document its constraints, plan its modernisation, break the work into reviewable tasks, and implement one safe step at a time.
That is an important difference.
Kiro does not remove me from the process. Instead, it changes my role. I spend less time writing every line manually and more time defining requirements, preserving important behaviour, reviewing architectural decisions, and validating the result.
In this guide, I will demonstrate how to use Kiro to begin modernising a legacy website without immediately rewriting everything.
What Is Legacy-Site Modernisation?
A legacy website is not necessarily a bad website.
It might still serve users every day. It may contain valuable content, rank well in search engines, support important business processes, or integrate with systems that cannot easily be replaced.
However, it may also contain:
- Outdated frameworks or dependencies
- Repeated HTML, CSS, or JavaScript
- Inconsistent components and styling
- Limited automated testing
- Accessibility problems
- Slow build or deployment processes
- Undocumented architectural decisions
- Code that only one person understands
- Features that everyone is afraid to change
Modernisation means improving these systems while protecting what already works.
That could include:
- Updating dependencies
- Introducing reusable components
- Improving accessibility
- Replacing outdated build tooling
- Improving performance and responsiveness
- Adding tests and automated checks
- Moving toward a more maintainable architecture
- Migrating one page or feature at a time
Modernisation should not automatically mean a complete rewrite.
A rewrite can accidentally remove years of hidden business rules, search engine optimisation, analytics, accessibility fixes, and user expectations. A safer approach is often to begin with a small vertical slice: one feature that can be modernised and validated from beginning to end.
What Is Kiro?
Kiro is an AI-powered development environment that can work with the context of an existing project.
You can use free-flow chat with Kiro’s Default agent to explore a codebase, ask questions, investigate errors, and make targeted changes. When the work becomes more complex, you can move into a structured Spec workflow.
A standard Requirements-First Spec progresses through three main artifacts:
- Requirements: What must the system do?
- Design: How should the solution work?
- Tasks: What implementation steps are required?
These artifacts are stored with the project, usually under:
1
2
3
4
.kiro/specs/<feature-name>/
├── requirements.md
├── design.md
└── tasks.mdKiro also supports Steering, which provides persistent project instructions. Steering helps the agent understand your technology choices, project structure, coding conventions, accessibility rules, and modernisation boundaries.
Together, Specs and Steering address two common problems with AI-assisted coding:
- Prompts lose context.
- Generated code may not follow the project’s real requirements.
What Is Spec-Driven Development?
Spec-driven development means agreeing on the intended outcome before allowing implementation to become the main activity.
Consider this prompt:
Modernise my website.
It sounds reasonable, but it leaves several unanswered questions:
- Which part of the website?
- Which behaviours must be preserved?
- Can the URLs change?
- Is the visual design changing?
- What browser support is required?
- Must existing analytics continue working?
- What accessibility standard should be met?
- How will we determine whether the migration succeeded?
Without these answers, an AI agent may produce technically impressive code that solves the wrong problem.
A Spec transforms the vague request into something testable.
For example:
WHEN a visitor opens an existing public URL, THE SYSTEM SHALL continue to serve the corresponding content without requiring a redirect from a broken URL.
Or:
WHEN a visitor navigates the header using only a keyboard, THE SYSTEM SHALL expose every interactive item in a logical focus order.
The purpose is not to produce documentation for its own sake. The purpose is to make the intended behaviour explicit before code changes begin.
Hands-On: Modernising a Legacy Website With Kiro
For this walkthrough, imagine that we have an older website with a hard-coded header, duplicated navigation across several pages, ageing dependencies, and limited accessibility support.
Instead of asking Kiro to rewrite the whole website, we will modernise the header and navigation as our first vertical slice.
Step 01: Protect the Existing Website
Before involving an AI agent, put the project under version control and confirm that the current site still runs.
Create a dedicated branch:
1
git switch -c modernise-site-navigationRecord the current baseline:
- How the application is installed
- How the development server is started
- How the production build is created
- Which pages currently work
- Whether tests, linting, or type checking already exist
- Which URLs and user journeys must be preserved
Take screenshots of the existing pages. If possible, record baseline performance and accessibility results.
AI can help with implementation, but it cannot preserve behaviour that nobody has identified.
Step 02: Ask Kiro to Understand the Project Before Editing It
Open the project folder in Kiro. Start in Supervised mode if the project is unfamiliar or sensitive so that changes remain easy to inspect.
Use project context such as
#repository and #codebase, then ask Kiro to investigate without modifying files.Example prompt:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
Analyse this legacy website before making any changes.
Using #repository and #codebase, identify:
1. The application entry points
2. The current framework and build tooling
3. How pages, styles, and scripts are organised
4. Where navigation is defined or duplicated
5. Existing test, lint, and build commands
6. Outdated or risky dependencies
7. Behaviour that could be broken during a migration
8. A small vertical slice suitable for the first modernisation Spec
Do not edit any files yet. Explain your findings and list any assumptions.This distinction matters.
“Analyse first” reduces the chance that the agent begins changing code before understanding how the application fits together.
You can also provide:
#fileor#folderfor targeted source context#terminalfor real build errors#problemsfor current editor diagnostics#git diffwhen reviewing changes#currentfor the active file
The more precise the context, the less the agent has to guess.
Step 03: Establish the Baseline
Ask Kiro to run or identify the project’s existing validation commands.
For example:
1
2
3
4
5
6
7
8
9
10
11
Determine the existing validation workflow for this project.
Run only non-destructive, single-execution commands. Report:
- Whether dependencies install successfully
- Whether the production build succeeds
- Existing lint, type-check, and test results
- Current warnings that are unrelated to our changes
- Pages or behaviours that need manual verification
Do not fix anything yet.A baseline separates existing problems from regressions introduced during modernisation.
If the application already has twelve warnings, you do not want to mistakenly attribute all twelve to the first migration task. On the other hand, new warnings should not be dismissed simply because the project already contains old ones.
Step 04: Create Persistent Context With Steering
Repeatedly explaining the same rules in every prompt is inefficient and unreliable.
Kiro steering documents live in:
1
.kiro/steering/Kiro can analyse the repository and generate three foundation documents:
1
2
3
4
.kiro/steering/
├── product.md
├── structure.md
└── tech.mdThese documents capture:
- product.md: What the application is and who it serves
- tech.md: Technologies, commands, and technical constraints
- structure.md: Project organisation and code conventions
Generated steering is a starting point, not unquestionable truth. Review every file and correct assumptions before relying on it.
For the migration, we can add focused guardrails:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
inclusion: always
# Legacy Website Modernisation Guardrails
## Preserve existing behaviour
- Preserve all public URLs unless a redirect plan is explicitly approved.
- Preserve page titles, metadata, structured data, and indexable content.
- Preserve existing analytics and consent behaviour.
- Do not remove a feature because its purpose is unclear.
- Flag undocumented behaviour before changing it.
## Accessibility
- Interactive elements must be usable with a keyboard.
- Use semantic HTML before adding ARIA attributes.
- Preserve visible focus indicators.
- Images must retain meaningful alternative text.
- Navigation must expose an accessible name and logical focus order.
## Implementation approach
- Modernise one vertical slice at a time.
- Prefer small, reviewable changes over a complete rewrite.
- Reuse existing project conventions unless the approved design changes them.
- Do not add a dependency without explaining why it is needed.
- Run the relevant build and validation commands after each task.Steering supports different inclusion strategies:
alwaysfor short rules that apply everywherefileMatchfor guidance that applies to particular filesmanualfor instructions included only when requestedautofor specialised guidance Kiro selects when relevant
For example, CSS-specific guidance does not need to consume context while working on database code:
1
2
3
4
5
6
7
8
9
10
11
inclusion: fileMatch
fileMatchPattern: "src/**/*.{css,scss}"
# Styling Rules
- Use the existing design tokens before introducing new values.
- Avoid global selectors unless required for the documented reset.
- Test layouts at mobile, tablet, and desktop widths.
- Respect prefers-reduced-motion.Good steering tells the agent not only what rule to follow, but why the rule exists.
Step 05: Select a Small Vertical Slice
Do not begin with:
Rewrite the entire legacy website using the newest framework.
Start with a feature that is:
- Valuable to users
- Small enough to review
- Representative of the wider application
- Easy to validate
- Reversible if the approach fails
For our example, the first slice is the site header and navigation.
This slice allows us to test:
- Reusable components
- Responsive behaviour
- Accessibility
- Styling conventions
- Existing routes
- Analytics integration
- The build and deployment process
If the approach works, we can apply what we learned to the next slice. If it does not, we have not endangered the entire site.
Step 06: Generate a Requirements-First Spec
After exploring the codebase, ask Kiro to convert the discussion into a Spec.
Example prompt:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Generate a Requirements-First Spec for modernising the website header
and navigation.
The implementation must:
- Preserve all existing navigation destinations
- Preserve analytics events and public URLs
- Support keyboard and screen-reader navigation
- Match the existing visual identity
- Work at the project's currently supported breakpoints
- Avoid a site-wide rewrite
- Introduce a reusable navigation component
- Include a rollback strategy
- Use the project's existing validation commands
Treat undocumented behaviour as a question, not permission to remove it.Kiro will first create
requirements.md.Review it carefully. Ask:
- Are all user groups represented?
- Are the acceptance criteria testable?
- Are mobile and keyboard interactions included?
- Does the Spec preserve SEO and analytics behaviour?
- Are error and fallback states covered?
- Has Kiro made assumptions that need confirmation?
Do not approve the requirements simply because they look professional. Well-formatted requirements can still be incorrect.
Step 07: Review the Design
After requirements are approved, Kiro creates
design.md.The design should explain how the new feature fits into the existing application. For a navigation migration, it might cover:
- The reusable component structure
- The source of navigation data
- Desktop and mobile interaction models
- Styling boundaries
- Accessibility behaviour
- Analytics integration
- Compatibility with existing pages
- Testing and rollback strategy
Useful review questions include:
1
2
Which parts of this design are based on confirmed repository behaviour,
and which are assumptions?1
How does this design avoid requiring a big-bang migration?1
What is the smallest implementation that proves this architecture works?1
Which existing behaviours could regress, and how will each one be tested?The objective is not to select the most fashionable architecture. It is to select the safest design that meets the approved requirements.
Step 08: Review the Implementation Tasks
Once the design is approved, Kiro creates
tasks.md.A sensible task sequence might be:
- Capture navigation behaviour and route mappings.
- Add focused tests or verification criteria.
- Introduce the navigation data model.
- Build the reusable desktop navigation component.
- Add keyboard and screen-reader behaviour.
- Implement responsive mobile navigation.
- Preserve analytics event handling.
- Replace the legacy header on one page.
- Validate the first page against the baseline.
- Expand the component to the remaining pages.
- Run the complete build and regression checks.
- Document the migration and rollback procedure.
Tasks should be small enough to review independently.
“Modernise navigation” is not a useful implementation task. It hides too many decisions and makes regressions difficult to isolate.
Step 09: Implement in Supervised Mode
Specs structure the work. They do not determine how much autonomy Kiro receives.
Kiro supports:
- Supervised mode: where changes can be reviewed as the agent works
- Autopilot mode: where Kiro can perform allowed work end to end
For the first slice of a legacy migration, Supervised mode is usually the safer starting point.
Ask Kiro to execute only the first task or a small related group:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
Implement only the next incomplete task from the approved Spec.
Before editing:
1. Restate the task's acceptance criteria.
2. Identify the files you expect to change.
3. Explain how the change preserves existing behaviour.
After editing:
1. Run the most relevant validation.
2. Summarise the changes.
3. Report assumptions and unresolved risks.
4. Stop before beginning another task.Review the resulting diff with
#git diff.Check for:
- Unrelated formatting changes
- Unnecessary dependencies
- Deleted behaviour
- Hard-coded data
- Missing error states
- Accessibility regressions
- Changes outside the approved task
- Comments that explain what the code does rather than why it exists
As confidence grows and once task boundaries and validation are reliable you may decide to use Autopilot for well-defined work. Autopilot should increase speed, not remove oversight.
Step 10: Automate Repeatable Checks With Hooks
Kiro hooks can trigger actions when specific events occur.
For example, a hook can:
- Run linting after Kiro edits relevant source files
- Format generated code
- Run targeted tests after a Spec task completes
- Validate a production build after implementation
- Guard sensitive tools or operations
A useful modernisation sequence could be:
1
2
3
4
5
6
7
Kiro completes a Spec task
↓
PostTaskExec hook runs validation
↓
Build, tests, or linting fail
↓
The failure is returned for investigationHooks should be narrow and fast. Running the entire test suite after every small file edit may slow down development without improving feedback.
Use deterministic command hooks for deterministic checks. Do not use an AI prompt where a formatter, linter, type checker, or test runner can provide a clearer answer.
Also remember that file create, save, and delete hooks apply to agent-made changes and not every manual edit in the editor.
Step 11: Validate More Than the Build
A successful build does not prove that the modernisation succeeded.
Before completing the slice, verify the original requirements.
Functional Validation
- Do all navigation links still lead to the correct pages?
- Does mobile navigation open, close, and restore focus correctly?
- Are analytics events still emitted?
- Does the component work without JavaScript where required?
- Are existing routes preserved?
Accessibility Validation
- Can every item be reached with a keyboard?
- Is focus order logical?
- Is focus visible?
- Do screen readers receive meaningful labels and state changes?
- Does zooming or enlarging text break the layout?
- Is reduced-motion preference respected?
Visual Validation
- Does the result match the existing identity?
- Does it work at supported breakpoints?
- Are hover, focus, active, and error states visible?
- Are long labels and translated content supported?
Technical Validation
- Does the production build pass?
- Do linting and type checking pass?
- Are dependencies justified?
- Has bundle size changed significantly?
- Are there new console warnings?
- Can the change be rolled back cleanly?
The validation results should be compared with the baseline captured before implementation.
What Kiro Changes About the Developer’s Role
When I first wondered who would rebuild my websites, I imagined the answer might be:
The AI will do it.
The more accurate answer is:
I will rebuild them differently, using AI.
Kiro can help explore the repository, expose hidden complexity, draft requirements, propose architecture, create tasks, implement code, and run validation.
But I still decide:
- What should be preserved
- What should change
- Which risks are acceptable
- Whether the requirements are complete
- Whether the design fits the project
- Whether the generated code is understandable
- Whether the result is ready for users
This is not the removal of the developer. It is a movement from typing every line toward directing and validating the development process.
Myths About Agentic Development
Myth: Kiro will safely rewrite an entire legacy website from one prompt
Reality: A broad prompt can produce broad, difficult-to-review changes. Small Specs and vertical slices reduce risk.
Myth: A Spec guarantees that the implementation is correct
Reality: A Spec improves clarity, but incorrect requirements produce incorrect outcomes. Requirements, design, tasks, code, and test results still need review.
Myth: Steering eliminates the need to provide context
Reality: Steering preserves important guidance, but Kiro still benefits from explicit files, folders, repository context, terminal output, and concrete acceptance criteria.
Myth: Autopilot means giving up control
Reality: Autopilot controls how independently Kiro executes allowed work. Specs, permissions, hooks, version control, checkpoints, and reviews still define the boundaries.
Myth: AI-generated code is automatically secure and accessible
Reality: Generated code is a draft. Security, privacy, accessibility, performance, and compliance require deliberate requirements and validation.
Common Mistakes to Avoid
Starting with the whole website
Begin with one page, workflow, or reusable component.
Treating generated steering as fact
Review and correct every generated document. Legacy projects often contain misleading folder names, abandoned code, and outdated commands.
Describing only the desired technology
“Convert this site to React” describes a technology choice, not the required user outcome. Document behaviour, constraints, and success criteria first.
Failing to capture the baseline
Without a baseline, existing defects and new regressions become difficult to distinguish.
Combining modernisation with redesign
Changing the architecture, framework, content, branding, navigation, and user experience simultaneously makes regressions harder to identify. Separate these concerns where possible.
Skipping human review because the tests passed
Tests only cover what someone thought to test.
Possible Future
Spec-driven development could change how organisations approach legacy modernisation.
Instead of beginning with months of manual code discovery, development teams may use agents to:
- Map undocumented applications
- Identify repeated patterns and risky dependencies
- Recover requirements from code and user behaviour
- Propose incremental migration boundaries
- Generate tests around existing behaviour
- Maintain architectural and compliance rules through steering
- Implement independent tasks in parallel
- Keep documentation aligned with the system
The future may include agents that continuously compare production behaviour, approved Specs, and implementation changes.
However, the most valuable outcome will not be complete autonomy (even though it's what we all secretly want). It will be better collaboration between people and machines: humans providing purpose, judgement, and accountability while agents handle more of the repetitive analysis and implementation.
Summary
1. The Evolution of the Workflow
1
2
3
4
5
6
7
8
9
Copy code into ChatGPT
↓
In-editor code assistance
↓
Project-aware agent
↓
Steering + Specs + Tasks
↓
Controlled implementation2. The Spec Workflow
1
Explore → Requirements → Design → Tasks → Implement → Validate3. The Modernisation Loop
1
2
3
4
5
6
7
8
9
10
11
Select one vertical slice
↓
Capture existing behaviour
↓
Create and approve a Spec
↓
Implement small tasks
↓
Validate against baseline
↓
Apply lessons to the next slice🏁 Conclusion
My journey started with copying code into ChatGPT.
Then CodeWhisperer and Amazon Q Developer brought AI closer to my editor and daily development workflow.
Kiro represents another step in that journey. It does not only help generate code, it helps structure the process around the code.
That process matters when modernising a legacy website.
The safest place to begin is not:
Rebuild everything.
It is:
Understand what exists. Document what must remain true. Choose one useful slice. Agree on the requirements and design. Implement it in reviewable tasks. Validate the result. Then repeat.
Perhaps I was right that the new websites would not be built by me in exactly the same way as before.
But they still need my decisions, context, standards, and final approval.
The code may be increasingly agent-assisted.
The responsibility remains human.
Sources and Additional Resources
Kiro is an AI-powered development environment that helps you build software from prototype to production. One unified agent harness powers every surface (IDE, CLI, Web, and Mobile) so your configuration, specs, and steering work everywhere.
This guide walks you through Kiro's essential features by working with a real project. You'll learn how to set up steering files, build features with specs, automate workflows with hooks, and extend capabilities with MCP servers**.**
Specs or specifications are structured artifacts that formalize the development process for features and bug fixes in your application. They provide a systematic approach to transform high-level ideas into detailed implementation plans with clear tracking and accountability.
The Requirements-First workflow is the traditional approach to Feature Specs, starting with what the system should do before determining how to build it.
Which workflow should I choose?
Feature Specs support two workflows: Requirements-First and Design-First.
What is steering?
Steering gives Kiro persistent knowledge about your project through markdown files. Instead of explaining your conventions in every chat, steering files ensure Kiro consistently follows your established patterns, libraries, and standards.
Hooks run shell commands or agent prompts automatically when specific events happen in your session - the agent modifies a file, invokes a tool, or completes a task. You define the trigger and the action; Kiro handles the execution.
Autopilot mode (default)
Kiro works autonomously to complete tasks end-to-end. It can create files, modify code across multiple locations, run commands, and make architectural decisions without asking for approval at each step. You maintain control through the ability to view all changes, revert everything, or interrupt execution at any time.
Supervised mode
Kiro yields for your approval after each turn that contains file edits. Changes are presented as individual hunks, giving you fine-grained control to accept, reject, or discuss specific parts of each modification. You can also accept changes at the file level or accept all changes at once to continue. This approach gives you full visibility into each change and lets you guide the development process to maintain code quality standards.
Kiro uses a capability-based permissions system that gives you fine-grained, declarative control over what the agent can do. You define rules per capability with match patterns and explicit effects, replacing older binary trust models.
Agent sessions are exploratory. Sometimes the agent heads down the wrong path, or you want to try a different approach without losing what you have. Kiro gives you two distinct ways to go back: checkpoints restore your files to an earlier point in the session, and rewind forks your conversation at an earlier turn.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article