Learn / Expert AI Layer

Expert AI Layer for Software Development

Short answer

AI can already write functions, explain errors, generate tests, review code, and suggest architectures. For many developers, ChatGPT, Claude, Codex, and other coding assistants are becoming normal parts of the workflow.

But the more complex the project becomes, the more obvious the limitation of general-purpose AI becomes: it knows software development in general, but it does not automatically know how your specific system works or why it was designed that way.

It may know JavaScript, Rust, C, Verilog, or SQL. It does not automatically know:

• which architectural invariants must never be violated;
• why the team rejected an apparently obvious solution;
• which dependencies are forbidden;
• where a module boundary really sits;
• which failures have already occurred;
• which trade-offs are acceptable;
• which decision is current and which one is obsolete;
• when AI may propose a change and when it must stop and ask a person.

An Expert AI Layer for software development is a managed layer of engineering context between developer experience and AI. It stores not only documentation, but also principles, methods, decisions, exceptions, and boundaries that AI should account for when working with code.

Simplified:

Code + documentation
        ↓
architecture rules
+ invariants
+ decisions and rationale
+ exceptions
+ engineering methods
        ↓
Expert AI Layer
        ↓
ChatGPT / Claude / Codex / another AI
        ↓
code, review, analysis, or proposal

Why an AI coding assistant alone is not enough

A coding assistant works well when a task is defined by local code and common engineering practices.

For example:

• write a transformation function;
• explain a stack trace;
• generate a unit test;
• find an obvious bug;
• suggest a refactor for a small module.

The problem starts when correctness depends on project history.

AI sees a validation check and suggests removing it as redundant. The team added it after a real production incident.

AI suggests connecting two modules directly. The architecture deliberately forbids that dependency.

AI creates another service. The project follows a principle that no new service should be introduced if the problem can be solved inside an existing module boundary.

AI generates code that compiles, but violates a system invariant.

In every case, the output may look technically convincing and still be wrong for this particular system.

Where engineering knowledge actually lives

In a real software project, engineering knowledge is distributed across many places:

• source code;
• README files;
• architecture documentation;
• ADRs;
• issue trackers;
• pull requests;
• code review;
• postmortems;
• tests;
• comments;
• team chats;
• verbal explanations from experienced developers.

None of those sources alone is a complete model of engineering judgment.

The repository shows what is implemented.

An ADR may show what was decided and why.

A postmortem shows what failed.

Code review often reveals which rule the team actually applies.

An experienced developer knows when an exception exists.

An Expert AI Layer brings those elements together into reusable context.

What to preserve in an Expert AI Layer for software development

1. Architecture principles

These are durable orientations that apply across many tasks.

For example:

Do not introduce a new service if the problem can be solved inside an existing module boundary.

Or:

Recoverability is more important than a local performance gain.

A principle does not always dictate a specific implementation. It guides engineering decisions.

2. Architecture invariants

An invariant is a condition that must remain true regardless of implementation details.

For example:

A resource must have only one owner at any given time.

or:

An active object must not be modified before handoff completes.

These statements are especially important for AI because a locally attractive refactor can violate a global invariant.

3. Decisions and rationale

It is not enough to preserve:

Use option B.

Better:

Use option B because it preserves reversibility and avoids a dependency between modules X and Y.

Rationale helps AI understand when a decision is still valid and when it may need to be revisited.

4. Module and API rules

For example:

• who may call an interface;
• which dependencies are allowed;
• which module owns state;
• which data is immutable;
• which format is a stable contract;
• which changes require migration.

5. Engineering methods

Teams differ not only in architecture but also in workflow.

A project-specific method for changing a system module might be:

1. Identify affected invariants.
2. Retrieve existing decisions and constraints.
3. Check interface impact.
4. Prepare the smallest viable implementation.
5. Add tests for invariants and exceptions.
6. Review consequences.
7. Only then merge the change.

If AI knows the method, it can help enforce the process instead of merely generating code.

6. Exceptions

A general rule often looks simple until the first difficult case.

For example:

Dependency A → B is normally forbidden.

A real system may still have a verified exception for bootstrapping or a compatibility layer.

Exceptions often contain the most valuable engineering experience because they usually appear after a real limitation or failure.

7. Known mistakes and anti-patterns

It is useful to preserve explicitly:

• approaches already tested and rejected;
• recurring AI mistakes;
• dangerous shortcuts;
• implementations that look correct locally but break the system globally.

That way the next AI session does not start from the same failed idea.

8. AI boundaries

AI should know not only the coding rules, but also the boundary of its authority.

For example:

AI may propose a public-interface change, but must not treat it as acceptable without compatibility analysis.

Or:

If a change touches two architecture invariants, a developer review is required before a final patch is prepared.

A practical workflow: AI that improves with the project

A useful loop looks like this:

New task
   ↓
Code + current context
   ↓
retrieve applicable rules, decisions, and invariants
   ↓
AI proposes an implementation or analysis
   ↓
developer reviews
   ↓
new useful decision / exception / corrected mistake
   ↓
captured in the Expert AI Layer
   ↓
the next task starts from the accumulated level

The key question after a meaningful task is:

What did we learn today that AI should know in the next similar task?

The answer may be one short rule, one exception, or one piece of decision rationale.

That is where compounding begins.

Use case 1. Architecture design

General AI can propose several architecture options.

An Expert AI Layer adds:

• existing module boundaries;
• forbidden dependencies;
• compatibility requirements;
• team priorities;
• previous decisions;
• known exceptions.

The question changes from:

What is the best way to design this component?

into:

What is the best way to design this component inside the architecture and invariants we have already accepted?

Use case 2. Code review using project-specific rules

Generic code review typically looks for:

• bugs;
• complexity;
• duplication;
• security issues;
• style problems.

A team may also have project-specific rules such as:

Check:
- whether a new state owner has appeared;
- whether a module boundary is violated;
- whether a hidden dependency was introduced;
- whether a public contract changed;
- whether known exceptions are covered.

Now AI review becomes part of the team's engineering process instead of just an LLM-powered external linter.

Use case 3. Debugging and recurring failures

Debugging history is especially valuable material for an Expert AI Layer.

After a difficult incident, capture:

Symptom
Root cause
Diagnostic sequence
Which first assumption was wrong
Which test confirmed the issue
How it was fixed
When the fix should not be applied

The next similar incident no longer starts with a generic list of possible causes.

AI receives the history of real engineering experience.

Use case 4. Systems software development

Systems software is especially sensitive to hidden constraints.

The Sekura Noda tenant contains real materials for Sekura JS and Reganta OS.

For Sekura JS, the module model is explicit: one .sjs file describes one module, and module profiles define different roles. Separate materials define runtime layout and dispatch behavior for exported functions.

Reganta OS is documented as an architecture without a conventional process model, with system and user behavior organized around modules and project-specific interaction mechanisms.

This is not a conventional architecture from the perspective of a general model.

If AI receives only one source file, it may suggest a familiar Linux, POSIX, or application-runtime solution and thereby contradict the project itself.

So useful context should not look like:

Here is the source file. Fix the function.

It should look more like:

Here is the source file.
Here are the architecture invariants.
Here is the module model.
Here are the current interface decisions.
Here are forbidden assumptions.
Here are relevant exceptions.
Now propose the smallest compatible change.

That is the difference between AI that knows programming and AI that knows how this specific system is built.

Use case 5. Developer onboarding

A new developer usually reads documentation and source code, then gradually asks experienced teammates for explanations.

An Expert AI Layer can give AI access to verified team explanations:

• why a component is structured this way;
• what must not be changed casually;
• which approaches were already tried;
• which terms have project-specific meanings;
• where responsibility boundaries actually lie.

This does not replace a senior developer.

It reduces repeated explanations the team has already given many times.

Use case 6. AI agents working with a repository

When AI only suggests code, mistakes can be caught during review.

When an agent can:

• change multiple files;
• run tests;
• create migrations;
• update documentation;
• open pull requests;

boundaries become far more important.

Before acting, the agent needs to know:

What is it allowed to change?
Which invariants must be checked?
Which tests are mandatory?
Which changes require a human?
Which files or interfaces must not be modified automatically?

Tools give an agent the ability to act. An Expert AI Layer provides the professional logic that constrains those actions.

Expert AI Layer vs repository documentation

Documentation is necessary, but it solves a different problem.

They are complementary.

Documentation is one source for the layer.

Expert AI Layer vs ADRs

ADRs are an excellent way to preserve architecture decisions.

An Expert AI Layer is broader.

It may include:

• ADRs;
• individual invariants;
• coding rules;
• review methods;
• exceptions;
• lessons learned;
• debugging decisions;
• AI automation boundaries.

An ADR can be the source of important knowledge. The Expert AI Layer makes that knowledge part of the context AI can use in current work.

Expert AI Layer vs a system prompt

You can try putting everything into one large prompt.

That works for small projects.

As the project grows:

• the prompt becomes long;
• rules conflict;
• outdated content is hard to identify;
• a rule is hard to connect to one module or scope;
• rejected decisions remain next to accepted ones;
• the same huge prompt is sent even when most of it is irrelevant.

A managed layer allows the system to select only applicable context.

Expert AI Layer vs RAG over documentation

RAG helps answer:

Which documents are semantically relevant to this request?

For software engineering, that is often not enough.

AI still needs to know:

• which decision is accepted;
• which document is superseded;
• which rule has priority;
• where an exception applies;
• which scope matches the current module.

RAG can deliver source material. An Expert AI Layer governs its professional meaning and applicability.

How to capture new knowledge after code review

You do not need to preserve the whole pull request.

After a meaningful review, extract the durable conclusion.

Weak:

PR #314 — 47-message discussion.

Better:

Rule: module A must not access state B directly. Reason: B must remain the single owner of that state. Exception: diagnostic read-only interface. Scope: runtime modules version 2+.

This form is easy to reuse in future changes.

Use AI mistakes as a source of improvement

One of the cheapest sources of engineering knowledge is the corrections you repeatedly give AI.

If you often say:

• “No, that is forbidden in this project.”
• “This interface is immutable.”
• “Do not create a process; our runtime is different.”
• “This module does not own that memory.”
• “Check invariant X first.”

those corrections are candidates for persistent context.

A useful rule:

If you correct AI in the same way for the second time, the rule probably deserves to be stored explicitly.

A minimal Expert AI Layer for one repository

You can start without complex infrastructure.

Collect:

10 architecture rules

What must not be violated.

5 decisions with rationale

Why the architecture looks the way it does.

3 engineering methods

For example: changing a public API, investigating a failure, reviewing a new module.

5 known exceptions

Where general rules behave differently.

5 anti-patterns

What has already been tried and should not be repeated.

AI boundaries

What AI may do autonomously and what requires review.

That can already move AI significantly closer to your project's real engineering context.

What not to preserve

Do not turn the layer into a second copy of Git.

Usually you do not need to store separately:

• every commit;
• every line of code;
• every chat;
• every automatically generated AI proposal;
• temporary debugging hypotheses after an incident is resolved.

Preserve what should change future work.

Common mistakes

Mistake 1. Treating the repository as the complete knowledge base

Code shows implementation but often not rationale.

Mistake 2. Treating every ADR as a permanent rule

Architecture changes. Status and current applicability matter.

Mistake 3. Preserving only the happy path

The most valuable experience often lives in exceptions and failure modes.

Mistake 4. Giving AI every document without scope

A rule from one module may be incorrectly applied to another.

Mistake 5. Letting AI create its own engineering rules without review

AI may propose a draft. An accepted engineering rule should remain a managed decision.

Mistake 6. Locking engineering knowledge into one coding assistant

AI tools will change. Your engineering layer should remain yours.

Mistake 7. Never extracting a conclusion after difficult work

Then AI accelerates today's task but does not produce compounding value.

How to measure value

You do not need a complex metric to start.

Track:

• how many repeated explanations disappear;
• how many recurring AI mistakes stop recurring;
• how many past decisions are reused;
• whether onboarding becomes faster;
• how many review comments become durable rules;
• how often old debugging lessons help with new incidents.

The main question is:

Does the next task begin at the level of engineering understanding where the previous task ended?

Why this becomes more important as AI improves

The stronger coding models become, the less advantage comes from merely having access to them.

If the same powerful AI is available to millions of developers, advantage shifts toward the engineering context the model receives.

Two teams can use the same AI.

The first explains its architecture again every day.

The second captures after meaningful work:

• one new invariant;
• one exception;
• one decision rationale;
• one corrected mistake;
• one improvement to its method.

After a week, the difference is small.

After a year, the second team has an accumulated engineering layer built from real development work.

You cannot get that simply by installing a newer coding assistant.

Frequently asked questions

Does an Expert AI Layer replace documentation?

No. Documentation remains an information source. An Expert AI Layer adds managed rules, methods, decisions, exceptions, and boundaries.

Do I need RAG?

Not necessarily for a small project. For large collections, RAG or semantic search can help retrieve relevant sources. Retrieval does not replace status, scope, or engineering rules.

Do I need to fine-tune a coding model?

Usually not if the goal is to use changing architecture knowledge and decisions. That context is generally easier to manage outside the model.

Can I use the same layer with different AI systems?

Yes, if engineering knowledge is stored independently from a particular AI client and applicable context can be provided to the model you choose.

Can AI create new rules automatically?

AI can propose drafts based on code review, debugging, or discussion. Significant architecture rules should normally be confirmed by a person.

Is this only for large teams?

No. A solo developer also accumulates methods, architecture decisions, and recurring mistakes. For an individual developer, the layer can become long-term engineering memory.

Where should I start today?

Choose one active repository. Write down ten rules you repeatedly explain to AI or to new developers. Add known exceptions and the rationale behind the most important decisions.

Related reading

• What Is an Expert AI Layer
• Expert AI Layer Architecture
• How to Capture Tacit Knowledge for AI
• Expert AI Layer and AI Agents
• Expert AI Layer and MCP

Next step

Do not try to model the entire engineering organization at once.

Start with one project and one recurring task, such as code review or architecture changes.

Capture:

1. applicable invariants;
2. the work method;
3. criteria for a good solution;
4. known exceptions;
5. AI boundaries;
6. several past decisions with rationale.

That is enough to move from AI that helps write code toward AI that increasingly understands how you build the system.

Start building your Expert AI Layer

Every developer will gradually gain access to strong AI coding assistants.

The difference will not come only from the model.

It will come from what you have accumulated above it: architecture decisions, methods, constraints, exceptions, and lessons from your own development work.

Do not just use AI to write code. Start building an engineering layer that becomes stronger together with your project.

Start building your Expert AI Layer.

Start creating your Expert AI Layer

Back to Expert AI Layer