Architecture AI guide¶

This guide explains how to craft and refine architecture with AI on the Architecture page. The architecture AI flow in AIKOZO is not just a free-form prompt box and it is not just a rigid form. It combines:

explicit fragment selection
a standardized action choice: Validate, Align, or Enhance
optional user guidance in Optional query
quick reusable phrases
async preview, review, and apply/discard
findings that can suggest a next action

Use this page when you want AI help that stays bounded to a clear architecture context and still leaves the final decision with you. It matters because the quality of the result depends as much on choosing the right action and scope as it does on the prompt itself. Before you start, you should already know which architecture or flow fragment you want to work on and which problem you are trying to solve. A focused read usually takes around ten minutes, and the worked example is the fastest way to see how the pieces fit together.

The same action model now also applies to the Feature flow page, where the target kind is always Flows.

Start with the action choice¶

Before you type anything, decide what kind of help you want.

Architecture tabs present the actions in the usual working order: Validate, Align, then Enhance. Start with read-only diagnosis, act on fit or reuse findings, and improve expression once the structure is right.

Action	Use it for	Expected output	Does it change the architecture?
Validate	Find problems, ambiguities, missing links, weak ownership, duplication, or misalignment.	Findings only.	No.
Align	Bring selected fragments closer to existing architectural conventions, shared structures, reuse patterns, and neighboring context.	Preview of aligned fragments plus findings.	Yes, after review and apply.
Enhance	Improve clarity, wording, structure, responsibilities, and completeness of the selected fragments.	Preview of improved fragments plus findings.	Yes, after review and apply.

Validate¶

Choose Validate when you are unsure what is wrong, what is missing, or what should happen next.

Good uses:

check whether an interface has the right owners
detect weak module boundaries
verify that a feature component really reuses shared structures instead of duplicating them
confirm whether entity and interface relationships are coherent

What to expect:

no architecture content is modified
you get findings you can review and often copy into follow-up work
some findings may offer a recommended Align or Enhance action

Align¶

Choose Align when the selected fragments do not fit the surrounding architecture well enough.

Good uses:

connect a flow-local interface to the right owner component
replace duplicate local concepts with reuse of already existing implementation-level Architecture concepts
bring naming, placement, and references in line with the surrounding architecture
propagate a small but necessary correction to nearby fragments

What to expect:

only the selected fragments may be updated
non-selected fragments remain untouched
implementation-level Architecture still acts as read-only reference, not as a writable target

Enhance¶

Choose Enhance when the selected fragments are basically on the right path but need to become clearer, more complete, or more explicit.

Good uses:

sharpen responsibilities of a component
make interface contracts clearer
improve entity definitions and relationships already implied by the architecture
remove ambiguity or weak phrasing

What to expect:

only the selected fragments may be updated
non-selected fragments remain untouched
the change stays local and bounded, not like a broad rewrite

How the architecture AI flow works¶

The page is organized to keep AI work reviewable.

Open one artifact tab: Modules, Components, Interfaces, Entities, ADRs, or on the Feature flow page select Flows.
Select one or more fragments of the same kind.
Pick the action you actually need: Validate, Align, or Enhance.
Add optional guidance in Optional query when you want to steer the run.
Queue the action.
Review the result in the enhancement history for the active tab.
Use Re-run, Apply, or Discard after review.

This structure matters. AIKOZO is designed so that you do not have to describe the entire problem from scratch every time. The selected fragments, the active tab, the read-only scoped context, and the optional query work together.

What “scoped context” means in practice¶

This is the newer, stricter form of what older documentation called current architecture context.

The AI still receives supporting context, but that context is read-only.

Current scoped context contains only the minimum related information needed to understand the selected fragments.
Implementation Architecture context is additional read-only context, especially useful for Feature flow alignment.

This means:

Validate stays read-only.
Enhance and Align may modify only the selected items.
non-selected fragments remain unchanged even when they are visible as context.

Real-world example: fixing a notifications flow¶

Consider a Feature flow for order processing. You have:

an integration interface if.int.notifications
a publisher candidate cmp.orders.api
a local consumer cmp.notifications
a module mod.messaging

The problem is typical:

the interface exists
the publisher and consumer are not modeled coherently
ownership looks incomplete
the fragments feel related, but you do not want a broad redesign

Step 1: start with Validate¶

Open Interfaces, select if.int.notifications, and run Validate.

A useful query might be:

Check ownership, publisher-consumer clarity, and whether this interface fits the surrounding messaging architecture.

Why start here:

you first want diagnosis
you do not yet know whether the real next step is Align or Enhance

Review the findings carefully. If a finding includes a recommended action, the finding can open a prefilled follow-up modal for you.

Step 2: use the recommended Align action¶

Suppose a finding suggests that the interface should align with the concrete publisher and nearby messaging context.

Click the finding’s Align button.

The modal is opened for you with:

the correct target tab
the relevant target fragments selected
the recommended action text prefilled in Optional query

This is where the flow becomes more than “prompt only” UX. The next action is not just text. It is a scoped continuation of the previous review step.

Step 3: review the Align preview¶

After the queued run finishes, open the history item and inspect:

Validation
Before
After

In this example, a good Align preview might:

connect if.int.notifications to the right owner or publisher fragment
keep the module and naming conventions coherent
update only nearby messaging fragments needed to preserve consistency

If the result is directionally correct but not sharp enough, use Re-run.

Step 4: use Enhance only after the structure is right¶

Once the relationships are coherent, run Enhance on the most relevant fragment set, often Components or Interfaces.

A useful query might be:

Clarify event publishing responsibilities and make the contract explicit without changing the overall architecture.

This is a good Enhance prompt because it asks for stronger expression, not structural discovery.

Step 5: finish with one more Validate pass¶

When the local refinement is done, run Validate again on the final fragment set you care about.

This last pass answers:

are responsibilities clearer now
are owners and references coherent
did the previous action leave new ambiguity behind

If the findings are now minor or informational, you are close to applying and finalizing.

How to write better Optional query text¶

The Optional query field should narrow the run, not replace the built-in context.

Good queries:

Clarify ownership and event flow, but keep current IDs and module structure.
Validate whether these components reuse shared notifications patterns instead of duplicating them.
Align naming and references with the surrounding messaging context.
Enhance the interface contract so downstream consumers are explicit.

Weak queries:

Make it better.
Refactor everything.
Do whatever makes sense.
Rework the whole module.

The better pattern is:

say what kind of problem you care about
say what should stay stable
keep the request local

Use saved phrases deliberately¶

Saved phrases are most useful when your team repeats the same review moves.

Examples:

merge these and propagate updates to references to keep consistency
clarify ownership and dependency direction
validate reuse against surrounding implementation architecture
tighten responsibilities without expanding scope

Important details:

phrases are remembered separately per action and artifact tab
only up to three suggestions are shown in the modal
favorites are prioritized
on the Profile page you can favorite or delete saved phrases

Treat saved phrases as reusable steering hints, not as replacements for review.

Read findings as decision support¶

A finding is not always a command to apply immediately.

Use findings in three ways:

as review evidence
as input for a follow-up action
as a signal that the current scope is too small or too broad

When a finding includes a recommended action:

hover the Align or Enhance button to read the recommendation text
click the button when you want to open the next scoped action
still review the selection and query before you submit

Review checklist before Apply¶

Before applying an AI result on the Architecture page, check:

does the action really match the intention: Validate, Align, or Enhance
are the changed fragments still local to the intended architecture area
do the Before and After sections show coherent references
did the run improve clarity, not just add more words
is the graph in Overview now easier to explain
do the findings now read as minor follow-up items rather than structural warnings

Common mistakes¶

Using Enhance when you really need Validate¶

If you do not yet know the problem, diagnose first. Otherwise you risk asking for changes before you understand the real issue.

Writing a whole architecture brief into Optional query¶

The page already provides structure. Use the query to steer, not to restate the entire architecture.

Applying the first preview too quickly¶

Use Re-run when the direction is right but the result is not review-ready.

Selecting too much at once¶

AI architecture actions work best when the scope is small enough to review clearly. If the result feels broad or vague, reduce the selected set and try again.

Recommended working pattern¶

For most real architecture work, this pattern is reliable:

Validate to expose the real issue.
Align when the main problem is fit, reuse, or consistency.
Enhance when the structure is already right but the expression is weak.
Validate again before applying the final local change.

That loop is the practical center of architecture crafting with AI in AIKOZO.