Forem: huoru

Last month I watched Claude Code confidently rebuild a Redis queue my team had abandoned three weeks earlier. The decision lived in a Slack thread, two PR comments, and three engineers' heads. Code search saw the files. It couldn't see the decision.

huoru — Thu, 07 May 2026 02:40:35 +0000

huoru

May 7

We Have Code Review. We Need Intent Review.

#ai #programming #claude #softwareengineering

Comments

9 min read

We Have Code Review. We Need Intent Review.

huoru — Thu, 07 May 2026 02:22:52 +0000

We Have Code Review. We Need Intent Review.

Last month I watched Claude Code confidently rebuild a Redis queue that my team had abandoned three weeks earlier.

The repo had redis.go, TODOs scattered around, and redis configured in docker-compose.yml. Claude saw all of this and reasonably wanted to finish what looked like a half-built feature.

The problem: we'd already decided not to use Redis. Replication lag had been causing duplicate billing events, and the team made the call to rip it out. That decision lived in a Slack thread, a couple of PR comments, and the heads of three engineers.

Code search saw the Redis files. It couldn't see the decision.

This is a specific failure mode I keep running into, and the more I look at it, the more I think we're missing an entire layer of review in our AI-assisted workflows.

We have code review. We need intent review.

The Problem Isn't What the AI Wrote

Most discussions about AI coding focus on the output: did it produce good code? Was the architecture sound? Are the tests passing?

But the failure mode I'm describing is different. The agent isn't writing bad code. It's writing reasonable code based on the wrong historical premise.

Think about how a senior engineer behaves when they touch unfamiliar code. They don't just read the function signature and start typing. They:

Check the commit history to understand why it was written
Look for related PRs that touched this area
Ask the team in Slack: "anyone know why we did it this way?"
Pause before changing patterns that look intentional but unfamiliar

This isn't because senior engineers are smarter than AI agents. It's because they have humility toward unfamiliar code. They've been burned enough times to know that what looks like dead weight is sometimes load-bearing, and what looks like a half-built feature is sometimes an explicitly abandoned approach.

AI agents don't have this humility. They're optimized for agreement, not interrogation. If the code looks half-built, the agreeable thing to do is finish it. If a TODO looks reasonable, the agreeable thing is to address it. The agent extends rather than questions.

This works fine for greenfield code. It breaks badly in any codebase older than a few weeks.

Why Existing Solutions Don't Solve This

When I describe this problem, people usually point to existing tools. Each of these has a real role, but none of them fully addresses what I'm calling intent review.

AGENTS.md / CLAUDE.md — These work for the not-todos you can anticipate. You can write "don't use Redis" once you know Redis is dead. But what about the decision you'll make next week? Or the one your colleague made yesterday? AGENTS.md only covers the past you've already documented. New decisions don't write themselves into the file.

ADRs / RFCs — Heavy enough that most teams stop maintaining them after the first quarter. Even when maintained, they're written for human readers, not for agents querying contextually before a code change.

Wiki / Notion / Confluence — Documentation drifts from code. The wiki page from six months ago still says "we use Redis." Agents don't naturally query wikis the way they query code, and even if they did, they'd find a free-form page that doesn't structure decisions vs. risks vs. rejected alternatives.

PR descriptions — Buried in GitHub. Searchable in theory, ignored in practice. Agents don't proactively pull PR descriptions for related code regions.

Agent harnesses with built-in memory — Tools like jcode capture session memory automatically and inject it into future sessions. This works within the harness. But the moment you switch agents, change tools, or have a teammate who uses a different setup, the memory is gone. You're locked into the harness.

Each of these is a partial answer to a real problem. None of them gives an agent reliable, structured access to your team's actual historical decisions before it touches unfamiliar code.

Code Review vs. Intent Review

Code review answers: "Is this change well-implemented?"

Reviewers look at the diff. They check correctness, style, test coverage. They might catch a bug or suggest a better pattern. This is essential, and it works.

But code review is a poor place to ask: "Is this change well-conceived in light of what the team already decided?"

That question requires the reviewer to know the entire decision history of the codebase. To remember why a particular pattern exists. To recall that Redis was abandoned three weeks ago for replication reasons. Most reviewers don't have this context. Even the original author often doesn't, six months later.

Intent review is a different kind of review. It happens before code is written, not after. It asks:

What does the team already know about this area?
What decisions were made, and why?
What was considered and rejected, and for what reasons?
What risks were identified that haven't been mitigated yet?
What architectural claims are load-bearing?

For a human engineer, this kind of review happens informally—a quick Slack message, a glance at the commit log, a 30-second conversation with the person who wrote the original code.

For an AI agent, it doesn't happen at all. There's no equivalent to "let me ask the team." The agent reads the current state of the code and infers from there. The historical signal isn't accessible.

What Intent Review Looks Like

Intent review needs three properties to actually work:

1. Decisions need to be structured, not free-form.

A wiki page that says "we decided to use JWT" is fine for human reading. An agent needs to know: what was decided, what was rejected, why, what risks were identified, what files this touches, what subsystems it affects, what claims about the architecture were load-bearing.

Free-form prose hides this structure. An agent has to re-parse the entire document every time. Structured records let agents query specifically: "show me decisions affecting auth that mention session handling."

2. Decisions need to live near the code, not in a separate system.

Wiki pages drift from code. Notion pages get forgotten. Slack threads get buried. The only thing that reliably stays connected to code is git itself.

If decisions live in git, they survive everything that affects code: clones, forks, branches, time. Six months from now when the agent is touching this area, the decision is right there—same place as the code, fetched together, queryable in the same workflow.

3. The query must happen automatically, before the change.

If the agent has to be reminded "check the wiki first," it won't. If decisions live in a sidebar that requires explicit lookup, agents skip it. The query has to be part of the agent's normal workflow—the same way it grep's for symbol definitions before refactoring.

This is the hard part. An agent that already runs grep and read_file before editing should also run something like intent_context before editing. The friction of looking up decisions has to be lower than the friction of guessing.

What I'm Building

I've been working on this with a tool called Mainline. It records team intents and decisions as structured records in git itself, where any agent can query them before making changes.

Architecturally:

refs/heads/_mainline/actor/<id>   # per-developer append-only log
refs/notes/mainline/intents       # links between commits and intents

Each sealed intent contains:

summary.what and summary.why
decisions[] with rationale and rejected alternatives
risks[] with mitigations
fingerprint covering touched files, subsystems, and architectural claims

Before an agent changes code, it runs something like mainline context auth and pulls structured records about past decisions affecting the auth area. After completing work, it seals a new intent with what was decided, what was considered, and what risks remain.

A few design choices that took me a while to settle on:

Process-based CLI, not a daemon. I considered a background daemon that would auto-capture activity. I looked at how that played out in similar tools (git-ai's daemon hits issues with macOS sleep, socket handling, zombie processes). Git itself is already a battle-tested protocol for this kind of thing. I didn't need to reinvent it.

Intent-level, not line-level. Line-level attribution (which file, which line, by whom) sounds appealing but is fragile. A formatter run, a git mv, a copy-paste, an --amend—any of these can break line-level tracking. Intent is task-level. Text transformations don't change the semantic meaning of "we decided X for reason Y."

Explicit seal, not automatic capture. Auto-capture sounds magical, but it produces a lot of noise: every keystroke and tool call gets recorded, and querying that later is harder than it looks. Explicit sealing has friction—the agent has to actively summarize what happened—but the resulting record is high-signal.

Append-only and immutable. Sealed intents can't be edited, only superseded. The original "what we thought at the time" stays intact. If we changed our minds, we add a new intent that supersedes the old one. The history of how thinking evolved is preserved, not overwritten.

The tool is open source (Apache 2.0) and currently in private beta. It's at mainline.sh if you want to look. I'm not pitching here—the point of this post is the idea, not the tool. If you build a different implementation of intent review that works better, I'd be genuinely interested in seeing it.

Where This Fits

There's a lot of energy right now in what people are calling compound engineering—the idea that each completed task should make the next one easier through accumulated learning. Tools like learning loops in Claude Code, the work Every is doing, the Ralph Loop pattern, all gesture at the same insight: AI coding workflows should accumulate knowledge instead of resetting every session.

I think compound engineering is heading the right direction, but it's missing a foundational layer. Most current implementations of "compound" rely on:

.claude/ files that humans maintain manually
Plain-text plans committed to the repo
Vector memory inside an agent harness
Retrospectives that update config files

These work, but they share a property: the knowledge is captured somewhere adjacent to git, not inside it. Switch tools, switch agents, switch teammates, and the compounding stops.

Intent review—done right—is the git-native foundation that compound engineering needs. If decisions live in git refs and notes, then any agent, any tool, any teammate can participate in the compounding. The knowledge isn't trapped in one harness.

What I'm Still Figuring Out

I've been dogfooding Mainline for about a month with a small team. Some things have surprised me.

The friction isn't where I expected. I thought engineers would resist writing structured seal records. They mostly didn't—it turns out the agent does the writing, and engineers just review and adjust. The actual friction is teaching agents when to seal. Too eager and you get a flood of trivial intents. Too conservative and important decisions go unrecorded.

The benefit shows up later than I expected. The first week, mainline feels like overhead. By week three, you start hitting moments where you ask "why did we do this?" and the answer is right there in the intent log. By week six, agents start using past intents as context without being asked. The compounding is real, but it's not immediate.

Cross-actor coordination is harder than single-user. When it's just me, sealed intents are mostly notes-to-self. When two engineers work in the same codebase, intents become a coordination protocol. We had to add explicit conflict detection (when two intents claim incompatible architectural changes) because otherwise we'd discover the conflict at PR review time, which is too late.

I don't think I've solved intent review. I think I've built one specific implementation of an idea that the field needs to develop further. Different teams will need different implementations. The structured-records-in-git approach is one path; others will work too.

What This Means for AI Coding

Code review is fundamental to software engineering. We don't ship code without review, even when the author is excellent. We don't trust raw output, even from senior engineers. We have a layer of structured human attention applied to every change.

AI agents are now writing significant fractions of new code in many teams. They're not getting reviewed less—if anything, the review burden is going up, because reviewing AI-generated code is often more cognitively demanding than reviewing human code. The reviewer can't ask the AI "why did you do it this way?" the same way they'd ask a colleague. The intent isn't legible.

Intent review isn't a replacement for code review. It's a complementary layer. Code review catches bugs in implementation. Intent review catches bugs in framing—the agent solving the wrong problem, finishing abandoned work, contradicting recent decisions, ignoring identified risks.

Without intent review, every code review has to do double duty: check the implementation and verify the framing. Most of the time, framing checks fail silently. The reviewer doesn't know that Redis was abandoned three weeks ago, or that this auth pattern was deliberately avoided, or that this risk was already identified and mitigated elsewhere. They approve the code, and the broken framing ships.

I don't think this is a problem we can solve with better prompts or larger context windows or more capable models. It's a structural problem about where institutional knowledge lives. Right now it lives in heads, Slack, and PR comments—places agents don't reliably look. We need it to live somewhere agents do reliably look. For most teams, that means git itself.

We have code review. We need intent review.

If you're seeing this same failure mode in your team, I'd be curious to hear how you're handling it—or whether you've decided it's not a real problem. Either is useful to know.

Mainline is at mainline.sh. Source on GitHub. Apache 2.0. Currently in private beta with a small group. If you have a 5+ person team using AI coding heavily and want to try it, reach out.

I built Hika - an AI-powered PKM tool that thinks differently about knowledge exploration

huoru — Sun, 02 Feb 2025 04:17:02 +0000

Hey PKM community! I'm one of the creators of Hika, a new AI-powered knowledge search tool, and I wanted to share why we built it and our thoughts on the future of Personal Knowledge Management.

Why We Built Hika

https://hika.fyi?utm=redditPKM

As a heavy user of AI products and someone deeply interested in knowledge management tools, I noticed that while there are many AI search tools out there, they all feel surprisingly similar. Most importantly, they weren't really helping me think better or understand topics more deeply.

The main issues I kept running into were:

AI models weren't really understanding what I was trying to learn
Links and images were being thrown at me without actually helping me understand
When I got interested in a specific part of an answer, there was no way to dig deeper

How Hika is Different

Instead of following the usual Perplexity-style format (text + links + related questions + images), we decided to approach it differently:

Paragraph-Level Exploration: We split answers into segments because you might be interested in several different aspects of a response. Each segment can be explored further with follow-up questions or deeper dives.
Visual Knowledge Mapping: We use charts and diagrams not just to illustrate points, but to provide a completely different perspective on the information. This gives you an immediate "big picture" view while also highlighting connections between concepts.
Depth Over Convenience: Rather than providing "lazy answers," we focus on giving you multiple "clues" for multidimensional thinking about a single question.

Our Philosophy

We don't believe AI will completely replace human thinking anytime soon (or that it should). When people think about complex topics, they naturally organize information in a network-like structure, extracting and processing useful information according to their own unique standards. This personal processing can't be quantified, which is why current AI search tools can't give everyone a satisfying answer.

That's why instead of trying to give complete, one-shot answers, we focused on making Hika really good at deep information exploration. In other words, we want to make your thinking process smarter and more efficient, not replace it.

Early Days

We're still in the early stages of development, and we know there are many areas to improve - performance, user experience, and functionality. We're actively working on iterations and improvements.

Looking for Your Thoughts

As fellow PKM enthusiasts, I'd love to hear your thoughts:

How do you see AI fitting into your knowledge management process?
What features would make your PKM workflow more effective?
What are your biggest pain points with current AI search tools?

If you're interested in trying Hika or want to share feedback, you can find us at https://hika.fyi?utm=redditPKM We're actively working on improvements and really value community input!

Tired of AI Giving You 'Lazy Answers'? Here's Our Solution

huoru — Fri, 20 Dec 2024 14:05:26 +0000

Hika AI: Rethinking Knowledge Search

Hika AI is an AI-powered "knowledge search tool" designed to help you quickly extend your knowledge in related fields or dive deep into key points of a question through Hika's "different perspectives," providing more comprehensive results when searching for information.

hika search

Why We Created Hika

My partner and I are heavy users of AI products and have long been interested in knowledge and information-based products. When using AI search products, we found that despite the abundance of options, most are very similar and often feel inadequate. The reasons for this are:

The underlying models aren't smart enough to truly understand our intentions.
The answers provided contain many links and images, but these don't necessarily help us better understand the question.
When we're interested in a particular part of the answer, we can't delve deeper.

We realized that these issues stem from the product industry's fundamental understanding of the relationship between AI and human interaction, which has become a consensus for this entire category of products. Therefore, we wanted to try a different approach.

How Hika Differs from Other AI Search Tools

Existing AI search products are mostly similar to Perplexity, offering text answers + links + related questions + images. They look like public accounts, with exploration focused more on form rather than the substance of the question itself. Hika's approach differs in the following ways:

Enhanced Text Answers: We retain the text portion as the main body of the answer while adding targeted professional knowledge sources to meet the basic effectiveness of Q&A.
Paragraph-Based Exploration: We divide answers into paragraphs because you're likely to be interested in several points within a single answer, which are usually distributed across different paragraphs. Hika can further explore these paragraphs interactively, providing associated follow-up questions or more in-depth answers.
Graphical Explanations: We provide graphical explanations. Compared to text statements, charts themselves offer a different angle of interpretation. Hika's charts can extend related knowledge points while giving you an immediate "global perspective."

As you can see, we aim to provide you with multiple dimensions of thinking "clues" for a single question, rather than a one-step "lazy answer."

Our Philosophy

We don't believe AI can completely replace human intelligence in the short term. When thinking about problems, people tend to organize information in a web-like structure, extracting and processing useful information before reaching conclusions. Everyone has their own unique processing method and standards, which cannot be quantified. This is why current AI searches can't provide satisfactory answers to everyone.

Therefore, we don't aim for one-step answers. Instead, we focus Hika on deep-diving into information, greatly improving the efficiency of web-like information acquisition. In other words, using Hika, your thinking can become smarter and more efficient than before.

Note: Hika is currently in the early stages of product development and has many issues, including performance, user experience, and functional processes. We will continue to iterate on it extensively, and we are eager to hear your voice, whether in agreement or criticism.

We're glad you can participate in Hika's growth and hope you enjoy using it!