Every developer who's used an AI coding assistant has experienced this: you ask it to contribute to your project and it produces something that works but doesn't belong. The code compiles, the tests pass, but a seasoned contributor would never write it that way. The AI doesn't know your project's conventions, architectural decisions, or the unwritten rules that make a contribution feel native.
We solved this problem for human contributors decades ago. It's called onboarding.
When a new developer joins a project, they don't start writing code immediately. They:
An AI assistant that skips this process is like a contractor who starts coding without reading the project docs. Technically capable, but culturally oblivious.
The difference: A human stores onboarding knowledge in memory. An AI needs it stored in structured documentation that persists between sessions.
If you practice spec-driven development — writing requirements, design documents, and quality criteria before implementation — you already have the mindset for this. AI onboarding is simply extending that discipline to cover how your AI team member should think about your project.
The deliverable isn't code. It's a steering documentation system — a structured knowledge base that transforms your AI from a generic code generator into a project-aware contributor.
We (Kiro and me) developed this approach while contributing to JavaParser, a 6,000+ star open source project with strict architectural standards. After receiving maintainer feedback on our first PR that highlighted 8 code quality issues (not bugs — the code worked, but it bypassed project abstractions), we realized: the AI needed to be onboarded properly.
The maintainer's feedback boiled down to:
None of these were documented bugs. They were cultural knowledge — the kind you only learn by being part of the project. Exactly what onboarding is for.
We designed a layered knowledge system that balances always-available guidance with context-specific depth:
Three layers:
Core Principles — Non-negotiable rules that apply to every contribution. Architecture patterns, code style requirements, process essentials. Always loaded.
Quick Reference — Actionable guidance for common scenarios. Step-by-step workflows, checklists, decision trees, anti-patterns with corrections. Always loaded.
On-Demand Modules — Deep knowledge for specific contexts. Only loaded when relevant, keeping the AI's context window efficient for actual work.
With a 1M token context window, the always-loaded core takes ~0.35% of available context. Even with an on-demand module loaded, total steering overhead stays under 3%. The AI has 97%+ of its capacity available for actual work.
Compare this to a human: you can't "unload" your project knowledge when working. The AI's modular memory is actually more efficient than ours.
Read all existing project documentation and extract patterns:
Deliverable: Working steering system — immediately usable.
Study 50-100 recent merged PRs to learn implicit patterns:
Deliverable: Priority modules for highest-impact areas.
Comprehensive pattern extraction from project history:
Deliverable: Complete module library covering all major contribution scenarios.
Optimization and publication for broader adoption:
Deliverable: Published, community-shareable resource.
This is where spec-driven thinking pays off. We defined quality gates before starting:
The usability test is the critical one. After creating our steering system, Kiro walked through our actual PR scenario (fixing a visitor generator) using only the guide. Every decision point was covered. Every common mistake was documented with corrections.
This kind of task to step out of the context is hard for a human, but any AI can handle it easily.
Here's where it gets interesting. While building this system, we faced a practical problem: where do these steering files live? They don't belong in the project repo (the maintainers didn't ask for them). They need to be available regardless of which branch you're on. And ideally, other contributors could reuse them.
Then we discovered Kiro Powers.
Powers are Kiro's native mechanism for packaging specialized knowledge — exactly what we'd built. A Power bundles steering files with optional MCP tools, hooks, and activation keywords. When you mention relevant topics in conversation, Kiro loads the appropriate knowledge automatically.
Our steering system mapped almost 1:1 to the Power format:
javaparser-contributor/
├── POWER.md # Core principles + steering routing
└── steering/
├── quick-reference.md # Common scenarios
├── generator-development.md # On-demand: generator work
├── pr-workflow.md # On-demand: PR process
└── metamodel-patterns.md # On-demand: metamodel changes
This solved every problem at once:
The methodology we developed independently turned out to align perfectly with Kiro's product architecture. We were building a Power without knowing it.
Maybe Kiro knew about this approach all along, but kept it well hidden.
Before onboarding:
After completing Phase 0:
The Phase 0 investment: ~17 credits (about 1 focused session).
The estimated total investment (Phase 0-3): ~2,000 credits across 7-10 sessions.
The return: Every future session starts with "experienced contributor" knowledge, improving further with each phase.
This isn't about making AI produce better code in isolation. It's about making AI a real team member — one that:
When you onboard a human contributor, you invest days or weeks. The return is years of productive contribution. AI onboarding takes hours. The return is immediate, perpetual, and reusable — the knowledge never degrades, never gets forgotten, and can be shared with every contributor who uses AI assistance.
Minimal approach (30 minutes):
Ask your AI assistant:
Read all my project documentation and create a steering system with:
1. Core principles - Non-negotiable project rules
2. Quick reference - Common scenarios with guidance
3. Pattern index - Keyword lookup and gap tracking
Validate by simulating one realistic contribution scenario.
Full approach (Kiro Power):
Create a Power following the Kiro Power format:
POWER.md
with frontmatter, core principles, and steering routingsteering/
files for on-demand knowledge modulesThe key insight: Your AI assistant's quality ceiling isn't its model capability — it's how well it understands your specific project. Onboarding closes that gap.
Spec-driven development taught me to think before we code. AI onboarding extends that principle: think about what your AI needs to know before it contributes.
We completed Phase 0 and packaged it as a Kiro Power. We're now gathering real-world experience using it during actual development. The questions we're exploring:
Based on these experiences, we'll decide whether and when to proceed with deeper phases. The phased/agile approach means we can stop at any point with a useful deliverable — there's no all-or-nothing commitment.
The result isn't just better AI output. It's a reusable knowledge artifact that benefits every contributor — human or AI (but mainly for AI nowadays) — who works on your project. It's institutional knowledge preservation. It's accelerated onboarding. It's quality at scale.
Your AI pair programmer is ready to learn. The question is whether you'll invest in teaching it your project's way of working, or keep accepting "works but doesn't belong" code forever.
This methodology was developed during contributions to the JavaParser open source project using Kiro CLI. The approach is language-agnostic and applicable to any codebase with established conventions. Follow-up posts will share what we learn from real-world usage and deeper onboarding phases.