From Idea to Merged PR: How Claude Became Part of Our Engineering Workflow

Most teams use AI to autocomplete code. We use it to think.

Not as a shortcut. Not as a replacement for engineering judgment. But as a collaborator that has full context of our codebase, our product, and our problems, and that is available the moment we need it.

This is how that looks in practice at Linkana, from the first conversation about a new feature all the way to a merged pull request.

It Starts With the Idea

Before anyone opens a code editor, Claude is already in the room.

When a new feature gets discussed, we bring Claude into the conversation early. It has context of the full application: the architecture patterns we use, the database schema from schema.rb, the naming conventions, the existing flows. That context lets it ask the right questions and surface edge cases that would otherwise only show up during implementation.

The output is a Linear card with a clear problem description, well-defined acceptance criteria, and a list of things to watch out for. By the time an engineer picks it up, the thinking has already started.

When Something Breaks, the Flow Is Similar

Bug reports are not a separate workflow. They follow the same logic.

We have a Slack integration that feeds bug reports into the process automatically. Claude picks up the context, cross-references it with what it knows about the system, and writes the Linear card with possible failure points already listed.

When something lands in Sentry, we grab the issue ID, hand it to Claude via the MCP integration, and Claude traces the error through the codebase and suggests a fix. The engineer validates the scenario before and after. The distance between “something broke” and “here is what to do about it” collapsed significantly.

Breaking Work Into Small, Sequenced PRs

Once the card exists, the next challenge is scoping the work correctly.

This is where most PRs go wrong. An engineer picks up a card, starts coding, and three days later has a branch touching twelve files across four layers of the application. The work is done but the PR is painful to review.

We use Claude to break that down before it happens. We describe the feature, share the relevant parts of the codebase, and ask Claude to suggest a sequence of PRs that each work independently and do not break main.

The result is a stack of small, focused pull requests that tell a coherent story from bottom to top. We use Graphite to manage that stack, and if you want to understand how that workflow looks in practice, we wrote about it in detail in Small PRs, Big Velocity: How Graphite Changed the Way We Ship at Linkana.

Skills: Teaching Claude How Linkana Works

Before we put Claude to work on real code, we trained it.

Not in the abstract sense. We wrote skills using real examples from our own codebase: how we structure a Solid::Process, how we name STI subclasses, how we write Stimulus controllers, how we handle background jobs. Each skill lives in the right folder, scoped to the right context.

We also used Claude to write the skills themselves, prompting it to produce documentation in the format that Claude reads best. The result is a feedback loop: Claude helps us write better instructions for Claude.

One concrete example: our view layer is built with Phlex and RubyUI, which has its own conventions and component structure. We wrote dedicated skills for that too, and if you are not familiar with how Phlex works in production, HTML as Ruby: A Deep Dive Into Phlex and RubyUI From Production covers it in detail.

When the codebase evolves, the skills need to follow. We use Claude to suggest updates when product changes happen, so the context stays as accurate as possible without requiring a dedicated person to maintain it.

The Code Claude Generates Is Not Always Clean

This is worth saying plainly because most AI content glosses over it.

Claude sometimes generates code that works but reads poorly. Too many comments explaining things that do not need explaining. Variable names that are overly descriptive. Structure that is technically correct but does not match how our team writes Rails.

That requires human intervention. An engineer reads the output, trims what does not belong, aligns it with our conventions, and commits something they are actually proud of. Claude is not the last line of review. The engineer is.

What Claude removes is the blank page problem. The cognitive load of starting from nothing. The first draft is there, and the job becomes editing rather than inventing.

A good example of the kind of architectural decision Claude helps enforce is knowing when a model is doing too much. We had a case where a single model was handling completely different behaviors behind a chain of conditionals. Claude helped us see the natural seams and refactor it using Single Table Inheritance. That story is in The God Model That Kept Growing (And How STI Finally Killed It).

PR Titles, Descriptions, and the Reviewer’s Time

Once the code is ready, Claude helps with one more thing: communicating what changed.

A PR title like wip: form updates tells a reviewer nothing. We use Claude to generate titles and descriptions that are specific, structured, and honest about what the change does and what to pay attention to during review.

Combined with Graphite for stacked PRs, the result is a sequence of small, well-described changes that a reviewer can move through quickly and confidently. Each PR is one thing. Each description explains that one thing clearly.

The Setup That Makes It Possible

None of this works without Claude having real access to the codebase and the tools around it.

We recently moved away from devcontainers and toward local machine setup via Mise. The reason is practical: Claude Code, the Claude chat, and the Cowork tool all work significantly better when running on the local machine rather than inside a container. The setup is faster to get right, easier to maintain, and lets each engineer get the most out of the AI tools without fighting the environment.

Claude Code handles code-level tasks directly in the terminal. The Claude chat handles investigation, card writing, skill creation, and PR descriptions. The MCP integrations connect Claude to Sentry, Linear, Slack, and the rest of the tools we use daily. Everything talks to everything.

What This Is Not

It is not a replacement for engineering judgment. Every suggestion Claude makes gets validated by a human who understands the system and is responsible for what ships.

It is not magic. It took time to build the skills, set up the integrations, and develop the instinct for when to lean on Claude and when to think it through yourself. That investment paid off, but it was an investment.

And it is not finished. The workflow keeps evolving as the tools improve and as we learn what works.

What It Is

It is the closest thing we have found to a senior engineer who is always available, never loses context, and never gets tired of reading stack traces.

The features still take time to build. The hard problems are still hard. But from the first conversation about an idea to the last merged PR, Claude is in the room.

Building this kind of engineering culture at Linkana is something we think about seriously. If that resonates with you, take a look at linkana.com.