AI coding assistants are becoming increasingly capable of understanding repositories, suggesting implementations, and generating code.
But there is something I've been thinking about while developing CodeMeridian:
What happens to our understanding of a codebase when an AI assistant makes every implementation decision for us?
We can ask an assistant to fix a bug, refactor a service, or implement a feature. It might produce a working solution without us needing to understand much of the code involved.
That is useful when we want to automate routine work. However, sometimes the reasoning behind a change is just as important as the change itself.
We might want to understand why an implementation was chosen, which existing constraints it needs to respect, or what could break if we take a different approach.
This led me to develop Human Cognitive Seed, a capability in my open-source project, CodeMeridian.
With v1.0.47, I've expanded it with an interactive code challenge that lets developers evaluate proposed changes themselves, using the actual source code and existing project context.
What is Human Cognitive Seed?
Human Cognitive Seed started as a provider-neutral agent skill built around a simple idea:
AI should amplify human reasoning rather than automatically replace it.
The intended reasoning loop is:
Human idea → AI expansion → Human evaluation → Improved understanding
The skill encourages an AI assistant to preserve the developer's starting assumptions, introduce relevant evidence and alternative approaches, challenge potential weaknesses, and help develop a more informed understanding of a problem.
It supports four interaction modes:
Direct: Complete routine tasks without unnecessary questions.
Scaffold: Expand an existing idea with evidence, alternatives, and potential consequences.
Teach: Help someone learn through hints, attempts, and feedback.
Deliberate: Explore trade-offs, uncertainty, and alternative models when making consequential decisions.
The intention is not to turn every coding request into a lesson.
If I ask an assistant to format a file, I want it to format the file.
If I'm trying to understand a complex architectural decision, however, I might benefit from evaluating multiple approaches rather than immediately receiving a completed implementation.
The skill determines when that additional reasoning is appropriate.
You can find the complete instructions in the Human Cognitive Seed skill.
Connecting human reasoning to actual code
CodeMeridian maintains a persistent knowledge graph of a repository.
It indexes supported C#, TypeScript, and frontend code, exposing relationships and architectural context through MCP tools.
Human Cognitive Seed can use this graph to connect a developer's reasoning to an exact code node.
For example, imagine we're discussing a change to a validation method.
An earlier development session may have established that validation must happen before an external service is called.
That decision might not be immediately obvious from the method's current implementation.
CodeMeridian provides two tools to help preserve this context:
record_change_context stores a short decision, constraint, limitation, assumption, or follow-up against an exact existing code node.
get_change_context retrieves previously recorded context when that code is revisited.
Each stored statement has explicit provenance, allowing the assistant to distinguish between its own synthesized observations, a user's statements, and an explicitly approved summary.
The system also tracks whether the target code has changed since the context was recorded.
Importantly, these notes are treated as attributed, unverified memory. They are not automatically considered correct just because they exist in the graph.
The current source code, tests, and maintained documentation still need to be checked.
This creates a useful foundation for the interactive challenge.
Introducing the Change Context Code Challenge
The new challenge takes the reasoning workflow a little further.
Instead of immediately implementing a proposed change, an AI assistant can present several possible code solutions and let the developer evaluate them.
The challenge is grounded in a specific code node, its current implementation, relevant tests, and previously recorded change context.
The workflow looks like this:
- Find the relevant code
The developer describes a bug, implementation problem, or proposed change.
The assistant uses CodeMeridian to identify the relevant implementation and resolve an exact code target.
The developer doesn't need to know the method's canonical graph ID.
- Inspect the existing context
Before creating the challenge, the assistant examines the current source code, relevant tests, and any existing change-context notes.
This provides the evidence needed to construct meaningful alternatives.
- Generate possible solutions
The assistant creates three or four plausible code choices.
One or two choices are designated correct, and at least two must be incorrect.
The incorrect choices should represent realistic implementation mistakes rather than obviously broken or nonsensical code.
For example, a challenge involving a validation method could include alternatives that:
Preserve the existing validation constraint.
Accidentally bypass validation.
Handle validation through a different but valid implementation.
Introduce an unintended behavioral change.
The assistant provides feedback for each alternative, but the correct answers are initially hidden from the developer.
- Let the developer decide
The interactive MCP App presents the choices using radio buttons when one answer is required or checkboxes when two answers are required.
The developer examines the alternatives and submits their selection.
The application does not automatically choose an answer on the developer's behalf.
If the selection is incorrect, the current attempt is halted.
The developer receives feedback explaining the selected mistake and can retry without the application revealing the remaining answers.
When the correct selection is submitted, the challenge is marked as completed.
- Optionally preserve what was learned
After solving the challenge, the developer can write a short change-context note.
For example:
"Preserve validation at the application boundary before invoking external dependencies."
The note is attached to the exact code node associated with the challenge.
A future development session can retrieve that context when the same code is revisited.
The note is optional. Solving a challenge does not automatically create persistent memory.
This completes the intended loop: examine the problem, evaluate alternatives, receive feedback, and preserve a useful decision when appropriate.
What does the implementation actually validate?
There is an important distinction in how this feature works.
The challenge is not an independent compiler, test runner, or formal correctness verifier.
The AI assistant authors the alternatives and designates which answers are correct using the source code, tests, and retrieved context it has inspected.
The MCP server then validates the developer's selection against that predefined answer set.
That means the quality of the challenge depends on the quality of the assistant's analysis.
The correct choice is not automatically guaranteed to be the best implementation.
Developers should still evaluate the proposed solutions against the actual codebase.
The purpose is to provide an interactive reasoning scaffold, not to replace code review or automated testing.
How the challenge works internally
The implementation is separated into three primary components.
MCP tools
The challenge exposes three tools:
start_change_context_challenge
Creates a challenge for an exact code node after verifying that the target exists.
answer_change_context_challenge
Validates the developer's explicitly selected choice IDs and returns feedback.
record_change_context_challenge_note
Allows an optional user-written context note to be saved after a successful challenge.
The tools return versioned structured results and provide Markdown output for clients that do not render the interactive interface.
View the MCP tool implementation
Challenge state
The server maintains challenge state in a process-local store.
It validates the number of alternatives, required selections, and associated feedback.
Each challenge expires after 30 minutes.
Correctness information and feedback are kept in server-side challenge state rather than being included in the initial application-visible response.
A failed attempt does not reveal the answers that the developer did not select.
The challenge itself is temporary and is not stored as durable project knowledge.
View the challenge state implementation
Interactive MCP App
The UI is a self-contained HTML application exposed through an MCP App resource.
It renders the code alternatives, handles user selection, displays feedback, and unlocks the optional note form after successful completion.
The implementation includes a text-based fallback for MCP clients without interactive App support.
View the interactive app source
Keeping persistent context separate from source-code facts
One design decision I wanted to preserve was the distinction between objective code information and human or AI-authored context.
A developer's explanation of why a particular implementation was chosen is valuable, but it is not the same thing as a compiler-resolved relationship or a verified source-code fact.
CodeMeridian therefore stores durable change context separately from canonical code-node properties.
Context records are linked to exact code nodes and carry provenance information.
The ordinary graph queries do not automatically inject these notes into every result.
The assistant retrieves them when the relevant code is being examined or when an earlier decision may affect the proposed change.
This is intended to prevent old assumptions from silently becoming authoritative instructions.
It also makes it possible to preserve meaningful development history without turning the graph into a collection of unverified conversations.
Trying the Human Cognitive Seed workflow
The Human Cognitive Seed skill is included in CodeMeridian's agent-capability bundle.
After installing CodeMeridian, you can initialize the capabilities in your repository:
codemeridian init .
The generated meridian-agent-capabilities/ directory contains the skill and other agent guidance.
You can install or copy the skill into the appropriate location for your AI coding assistant.
For the interactive challenge, the CodeMeridian MCP server must also have experimental MCP Apps enabled:
Mcp_Apps_Enabled=true
MCP Apps are disabled by default, and interactive rendering depends on client support.
Clients without the interactive interface can use the Markdown fallback and submit explicit choice IDs.
Once your repository has been indexed and your assistant is connected to CodeMeridian, you can request a challenge using a prompt such as:
Use the Human Cognitive Seed workflow for this change:
Find the exact implementation target.
Inspect the current source, relevant tests, and
previously recorded change context.
Create a code challenge with four plausible
implementation choices.
Include one or two correct choices and at least
two realistic incorrect choices.
Do not reveal the correct answers.
Let me evaluate the alternatives and select
the answer myself.
If my selection is incorrect, explain the
selected mistake and let me retry.
After I solve the challenge, let me optionally
record a short change-context note.
The assistant should investigate the implementation before generating the challenge, rather than inventing alternatives from a rough description alone.
For additional examples and the normal change-context workflow, see the Change Context User Guide.
Why I wanted to build this
I don't think developers should have to choose between using AI to accelerate development and understanding the software they're building.
Sometimes I want an assistant to handle repetitive work and provide a completed implementation.
Other times, I want to explore an architectural decision, understand the consequences of different solutions, or develop a better mental model of an unfamiliar system.
Human Cognitive Seed is an experiment in supporting both ways of working.
The broader skill helps the assistant recognize when human-led reasoning matters.
CodeMeridian supplies repository-specific evidence and preserves relevant development context.
The interactive challenge gives developers another way to participate in the reasoning process rather than simply accepting the first generated implementation.
The aim is not to make coding slower.
It is to preserve the opportunity to understand important decisions while still benefiting from AI-assisted development.
And when something meaningful is learned, that knowledge can remain available for the next development session.
CodeMeridian is open source.
The Human Cognitive Seed change-context challenge is included in v1.0.47.
Repository: https://github.com/Driftya/code-meridian
Release: https://github.com/Driftya/code-meridian/releases/tag/v1.0.47.
Top comments (0)