DEV Community: Jai kora

Building Internal Tools That Make Your Team Scale Like Software

Jai kora — Sat, 16 May 2026 12:59:59 +0000

Building Internal Tools That Make Your Team Scale Like Software

I've been watching teams get drunk on internal tooling lately, and it's fascinating how predictably it goes wrong. The pattern is always the same: massive excitement about AI agents that can automate everything, followed by a Cambrian explosion of custom tools, then the slow realization that managing seventeen different automation systems has become a full-time job.

The tools that actually stick around follow what I call the "eat like a dog" philosophy. Dogs don't reinvent their entire diet every week. They find something that works and stick with it, making small improvements around the edges. Your internal tools should work the same way.

The best implementations I've seen lately embed themselves so deeply into existing workflows that they become invisible. Instead of creating a new ritual where everyone has to check the AI dashboard every morning, they surface insights in Slack where your team already lives. Instead of building a separate system for status updates, they pull from your existing tools and generate the summary automatically.

I keep seeing teams build elaborate custom interfaces for their AI tools when the real win is making them disappear entirely. The moment you ask someone to learn a new system or change their habits, adoption drops off a cliff. But when the tool just makes their existing work faster and smarter, it becomes indispensable.

The compound effect happens when your tools learn from your team's actual patterns instead of imposing theoretical best practices. Your AI should know that Sarah always asks about database performance in standups, so it proactively includes those metrics. It should recognize that the last three critical bugs came from the payment flow, so it flags changes there for extra review.

The teams doing this right aren't building tools that feel like AI. They're building tools that feel like having a really good senior engineer who never forgets anything and works all night preparing exactly what you need for tomorrow's decisions.

What's the one manual process your team does every week that makes everyone groan when it comes up?

The Planning Problem: Why Smart Engineers Are Stuck Solving Trivial AI Tasks

Jai kora — Sat, 16 May 2026 12:34:24 +0000

The Planning Problem: Why Smart Engineers Are Stuck Solving Trivial AI Tasks

Your engineers can delegate to AI. They can assess what comes back. They can even compound successful patterns into reusable workflows. But ask them to plan before they start coding, and you'll watch senior developers stumble around like junior engineers figuring out their first API integration.

This isn't a skills problem. It's a process problem that's wasting the most expensive talent in your organization.

The AI Skills Paradox

According to the 2024 Stack Overflow survey, 76% of developers spend time on tasks they consider below their skill level. Meanwhile, GitHub Copilot adoption shows 88% of developers use AI tools but only 23% report significant productivity gains. The math here is brutal: we're automating the wrong things while leaving the hard problems untouched.

Most engineering teams follow a predictable pattern when adopting AI tools. They excel at three of the four critical phases: delegation ("write this function"), assessment ("this code looks wrong"), and compounding ("save this pattern for next time"). But they systematically skip the planning phase, treating AI like an advanced autocomplete instead of a reasoning partner.

The result? Senior engineers spend their days generating boilerplate code and debugging obvious errors instead of solving the architectural problems that actually move the business forward.

What Real Planning Looks Like

Planning isn't writing a requirements document that nobody reads. It's teaching your AI assistant to think through the problem the same way you would, before any code gets written.

Consider the difference between these two approaches:

Without planning: "Build me a user authentication system"
With planning: "We need auth that handles three user types with different permission levels, integrates with our existing session management, and gracefully handles the edge case where enterprise users can belong to multiple organizations"

The first approach gets you a generic login form. The second gets you a solution designed for your actual problem.

Effective planning means decomposing complex features into clear problem statements, identifying integration points with existing systems, and explicitly calling out edge cases that would otherwise surface during testing. When you plan properly, your AI assistant can reason about trade-offs instead of just pattern-matching against Stack Overflow examples.

Why Teams Skip Planning

The reason teams avoid planning has nothing to do with laziness and everything to do with incentives. Planning feels slow when you can generate working code in seconds. Why spend an hour thinking through requirements when ChatGPT can spit out a solution right now?

Because that "solution" won't handle the complexity of your actual system. It won't consider your performance constraints, your data consistency requirements, or the fact that your users do weird things that break standard implementations.

Planning also requires a different kind of thinking. Delegation and assessment are reactive skills. You can get better at them through repetition. Planning is generative. It requires understanding the problem space well enough to anticipate what could go wrong.

This is exactly the kind of work that senior engineers should be doing. Instead, they're stuck debugging code that wouldn't exist if someone had planned properly in the first place.

The ROI Crisis

Here's why this matters beyond developer productivity. According to the 2024 McKinsey AI reports, 70% of companies report AI projects fail to move beyond pilot phase. Organizations invested heavily in AI tools expecting immediate returns, and now they're facing hard questions about value delivery.

The problem isn't the tools. The problem is how they're being used. When your most expensive engineers spend their time on tasks that could be handled by junior developers or automated entirely, you're not getting AI acceleration. You're getting expensive inefficiency with better syntax highlighting.

Companies that crack the planning problem see different results. Their AI projects tackle meaningful architectural challenges. Their senior engineers focus on system design and problem decomposition. Their code quality improves because problems get solved at the design level instead of patched in production.

Building Planning Into Your Workflow

The fix isn't complex, but it requires discipline. Before any AI delegation happens, teams need to answer three questions:

What problem are we actually solving, including edge cases and integration requirements?
How does this solution fit into our existing architecture and what are the potential failure modes?
What success looks like, beyond "the code runs without errors"

This takes time upfront. But it saves exponentially more time during implementation and debugging. More importantly, it ensures your AI tools are being used to solve real engineering problems instead of generating glorified tutorials.

The teams that figure this out first will have a significant competitive advantage. While everyone else is using AI for better autocomplete, they'll be using it for better architecture.

Stop wasting your senior engineers on junior problems. Make them plan.

Building ARCHITECTURE.md Files That Prevent AI From Making Silent Architectural Decisions

Jai kora — Sat, 16 May 2026 11:23:13 +0000

Building ARCHITECTURE.md Files That Prevent AI From Making Silent Architectural Decisions

A few weeks into our experiment with an AI coding assistant, I noticed something odd. Variable names were shifting. Not dramatically. A rename here, a slightly reworded method there. Each change seemed reasonable in isolation. Professional, even.

But collectively, they were rewriting our architecture one rename at a time.

The Silent Coup

It started innocuously. The assistant would suggest replacing a small, plainly named method with a longer, more "enterprise" sounding one. The PR looked fine. More descriptive, right? Then it began restructuring how we organized service classes, introducing new abstraction layers that felt Enterprise Java-ish. Again, each individual change passed code review because none were objectively wrong.

Our human reviewers saw isolated improvements. Our automated reviewer, another AI, rubber-stamped the changes because they followed general best practices. No linter flags a variable rename. No formatter catches architectural drift.

A few weeks later, our codebase felt foreign. The naming conventions had subtly shifted toward verbose enterprise patterns. Service boundaries had blurred as the assistant introduced "helper managers" and "utility coordinators." The original lean architecture was drowning in abstraction.

The honest truth hit during standup when someone asked: "Why does this keep coming up?" We had spent half our sprint discussions untangling unnecessarily complex class hierarchies that had not existed a month prior.

Why Traditional Safeguards Failed

This was not a tooling problem. Our static analysis caught syntax violations perfectly. Our formatters maintained consistent indentation. Linters enforced style rules religiously.

But architectural decisions live in the spaces between the rules. When the assistant chose composition over inheritance, or decided to extract a new service class, or renamed methods to follow different conventions, these choices were invisible to mechanical constraints.

Human reviewers failed too, and for understandable reasons. Who flags a PR that renames a couple of variables and extracts a helper method? The changes looked professional. They followed general principles we had all learned in computer science classes.

The AI reviewer was even worse. It enthusiastically approved changes that made the code "more maintainable" according to whatever training data informed its judgment. Two AIs agreeing does not create architectural coherence. It creates compounded drift.

What Actually Worked

I started keeping an ARCHITECTURE.md file. Not as punishment for the assistant, but as explicit guidance about our actual architectural decisions and why we made them.

The file documents our naming conventions, why we keep service classes thin, and why we avoid deep inheritance hierarchies. More importantly, it explains the reasoning behind these choices: performance characteristics, team preferences, and integration constraints.

Every time the assistant made a questionable architectural call, I updated the document. When it introduced unnecessary abstraction layers, I added a section explaining our preference for composition patterns. When it renamed methods to be more "descriptive," I clarified our naming philosophy and provided examples.

This created a feedback loop that actually worked. The assistant began suggesting changes that aligned with our documented architecture. Not because it suddenly understood our preferences, but because the context was explicit rather than implied.

The Documentation Defense

The ARCHITECTURE.md file serves as a kind of architectural constitution, a set of principles that constrain both human and AI decision-making. It is not comprehensive documentation of every class and method. It is the theory of the system: how business problems map to code structure, what rules must always hold, and why certain patterns are preferred over alternatives.

I organize it around decision rationale rather than implementation details. Instead of documenting what the code does, it explains why it is structured that way. This gives both humans and AI agents the context needed to make consistent architectural choices.

The file evolves with the system. When we change architectural direction, we update the documentation. When AI agents make questionable choices, we refine the guidance. It is a living document that captures institutional knowledge about how we build software.

The Uncomfortable Reality

AI coding assistants are exceptionally good at writing code that works. They are terrible at understanding why your architecture exists and what constraints shaped its evolution. Without explicit guidance, they will optimize for whatever patterns dominated their training data, usually enterprise Java or academic computer science examples.

This is not the assistant's fault. It is doing exactly what we asked: writing better code according to general principles. The problem is that "better" is contextual, and context lives in documentation that most teams never write.

The ARCHITECTURE.md approach is not elegant or automated. It requires discipline to maintain and vigilance to enforce. But it is the only method I have found that consistently prevents AI agents from silently rewriting your architectural decisions.

Because the alternative, discovering weeks later that your codebase has quietly become someone else's idea of good architecture, is far worse than the effort of writing it down.