As an engineer reviewing human code or AI code, the first thing I always scan a pull request for are architectural changes. Is the right code in the right place following codebase conventions? And is the domain well modelled?

I’ve never really enjoyed looking at the diff on GitHub and trying to extract this information which is buried in hundreds of lines of code. And now I don’t have to.

In recent posts I talked about strong codebase to conventions to enforce application architecture and domain modelling concepts. Those same conventions make it easy to identify architecture, and architecture changes, in your codebase. It therefore becomes trivial to add an architecture/modell to your pull requests (all via code without any LLM involvement.)

This type of simple architecture diff gets added as a comment to every PR:

Read the full article for free on my website (no sign in or anything required, no cookies, I just chose to host to own my content): https://nick-tune.me/blog/2026-09-08-architecture-and-model-diffs-via-conventions/

Architecture and model diffs via code conventions was originally published in Nick Tune’s weird ideas on Medium, where people are continuing the conversation by highlighting and responding to this story.

The latest adventure on my journey to automate software conventions (mostly for AI but also for humans) has involved Oxlint. A TypeScript linter written in Rust.

My colleagues at PayFit have been pretty impressed with its performance, so I used it to implement the first version of a concept I’ve been thinking about for a while.

The idea is very simple: every piece of code must have a label indicating what type of code it is. Is it a repository, a validator, an error, a formatter. Based on the label you can then apply rules about where the code lives and how it can be combined with other code.

For example, any code with the decorator /** @riviere-role cli-entrypoint */ can only live in a folder that matches the following pattern: src/features/{feature}/entrypoint. If you put that code in a different folder, Oxlint will report an error. And if you put other code in that location Oxlint will also report an error.

In the full post I walk through the TypeScript DSL I use to configure these rules, show how to go beyond location-based checks into coupling and role-level constraints, explain how to help AI agents recover when they hit a guard rail, and share why I’m leaning into extreme standardisation as a strategy for AI-assisted codebases.

Read the full post for free on nick-tune.me

In the previous couple of posts I shared an approach I’ve started using, to design Claude Code workflows as state machines in real code using domain-driven design concepts. And then how to make them more
declarative with DSLs.

It was suggested by Yves Reynhout to make the workflows fully event-sourced, by not storing the current state and only storing the events. Then deriving the current state from the events.

So I gave it a try. The implementation was a pretty boring event-sourcing implementation using SQLite for storage. However, the possibilities unlocked are quite exciting — in-depth observability of how my agents performed and where they spent their time implementing a feature, and the potential for cross-session trends analysis.

In the full post I walk through the observability features this unlocks — session timelines, rejection and hook denial counts, AI-powered analysis suggestions, journal entries, event log search — plus the architecture, cross-session analysis possibilities, and when this approach is actually worth it.

Read the full post on nick-tune.me

In the previous post I showed a hook-driven workflow engine that coordinates Claude Code agent teams from GitHub issue through to PR. Defining workflows as code improves determinism and allows us to unit test the workflows so we can put strong guardrails around Claude and ensure they are working.

The original version I created was fully implemented in code. The code had some basic design, separation of concerns and layering, but I was curious if I could make it even easier to see what each step of the workflow does without looking at lots of other code. I wanted something more declarative yet still type safe.

So I started working on a redesign to decouple the declarative workflow steps from the underlying execution mechanics to get the best of both worlds.

Full post on my website: https://nick-tune.me/blog/2026-03-01-workflow-dsl-domain-driven-claude-code-workflows/

AI works best for me when it takes care of the workflow itself and allows me to focus on the business goals and architecture. I don’t want to be constantly prompting and guiding the agent to do the right thing, to run code reviews etc. It’s not enjoyable and it’s boring.

I’ve had a lot of success introducing deterministic workflows on repositories I fully control. I own the lint rules, the git hooks, the code review steps, and I can bake those into the process. I am consistently getting good results.

However, I am not getting good results when I need to work in legacy codebases, or codebases where I do not control all of those parameters. How can I get Claude to apply the same workflow and coding standards in those situations?

The solution I’ve arrived at is Claude Code hooks. I realised that they can do a lot more than I understood. They allow a highly enforced workflow with strong guardrails, written in a proper programming language, with 100% test coverage.

In the full post I walk through the architecture of a hook-driven workflow engine, show the state machine that enforces transitions between planning, developing, reviewing, and committing phases, and share code examples from a working GitHub repo with full test coverage.

Read the full post on nick-tune.me → https://nick-tune.me/blog/2026-02-28-hook-driven-dev-workflows-with-claude-code

Hook-driven dev workflows with Claude Code was originally published in Nick Tune’s weird ideas on Medium, where people are continuing the conversation by highlighting and responding to this story.

My journeys with AI-assisted development workflows have recently been
focused on feedback loops in the process. What I notice is that as more of
the mechanical process is automated, it frees up time to focus on improving the quality and building quality in.

The majority of my learnings have been shifting left on the code review
process. Typically this will be feedback raised by CodeRabbit on the PR that I try to incorporate into the process so it is caught earlier or doesn’t
happen at all.

There are various touch points in the process where feedback can be applied. Sometimes it’s updating CLAUDE.md, sometimes it’s a custom lint rule. But sometimes, it’s actually going much further upstream and improving the quality of the specifications.

The full post is available on my personal website (for free, no cookies or anything, I just prefer to own my content ).

https://nick-tune.me/blog/2026-02-01-code-quality-feedback-loops/

I’ve reached a point where I’ve automated the development process for a single feature. Claude Code will take a github issue, implement it, run code reviews locally, raise a PR, respond to the PR feedback, and then tell me when it’s mergeable and ready for my review.

I was very happy with the setup, but not fully satisfied. It was reliable but not bullet proof. And there were still some niggles to iron out to make it solid.

To get to that solution, the answer was to use real code. The current approach relies on Claude running steps in order, aka--please-work

I’d extracted some logic to bash scripts to make it partly deterministic and leveraged subagents to decouple the main agent, but there was still room for the main agent to improvise (that’s a negative in this context).

With real code, this problem is solved. And there are many other advantages too. I recommend it.

Current challenges

As I explained in the last post, the current solution looks like this:

/complete-task
    │
    ▼
Main agent runs pipeline directly
    │
    ├── [Bash] Verify gate → FAIL → return to main
    ├── [Subagent] code-review subagent → FAIL → return findings + next steps
    ├── [Subagent] Task-check subagent → FAIL → return issues
    ├── [Bash] submit-pr subagent → captures output
    ├── Check reviewDecision (CHANGES_REQUESTED = not mergeable)
    ├── Address ALL CodeRabbit feedback (comments + nitpicks)
    ├── [Bash] Re-run submit-pr if fixes made
    └── Return SUCCESS with PR ready to merge

Most of the steps are bash or subagent, removing some orchestration and decision-making from the main agent. But the main agent still has to orchestrate the workflow (because subagents cannot spawn other subagents… I tried that).

The main agent has just implemented a feature so it’s context is window is occupied. It’s not fully focused on orchestrating this process and following the precise instructions, it’s a bit tipsy wobbling from side-to-side.

It sometimes handles responses from each step in different ways, like not responding to CodeRabbit feedback, or re-running the submit-pr step without starting the full pipeline again.

Rather than keep trying to write better prompts and pleading harder with Claude, I decided to use real code.

Real Code

With real code you get determinism. The orchestration logic is mechanical based on simple rules. You don’t need an LLM for that. The only part of the process that needs an LLM is the code review. So I put all of the orchestration in code and used Claude Code SDK for the code review steps.

What I love about the solution is that it’s largely type safe. The input and output of each step of the workflow is strongly typed. I’m using Zod schemas in TypeScript.

Now, the workflow looks like this…

Claude Command

Rather than being given a workflow to orchestrate, Claude is just told to run an nx command in the /.claude/commands/complete-task command.

# Complete Task

Run the complete-task pipeline to verify, review, and submit your work.

## Instructions

Run this command with a **10-minute timeout**:

```bash
pnpm nx run dev-workflow:complete-task
```

This is a long-running command that:
- Runs local verification (lint, typecheck, test)
- Executes code review agents
- Submits PR and waits for CI checks

Parse the JSON response and follow the `nextInstructions` field exactly.

It’s now a black box. Claude doesn’t know about the mechanics, it just waits for a result indicating the task succeeded or failed. If it failed there will be a list of errors to deal with.

Dev workflow as code

Now the complete-task command is implemented like this:

runWorkflow<CompleteTaskContext>(
  [
    verifyBuild,
    codeReview,
    submitPR,
    fetchPRFeedback,
  ],
  buildCompleteTaskContext,
  (result: WorkflowResult, ctx: CompleteTaskContext) => formatCompleteTaskResult(result, ctx.prUrl),
)

1. verifyBuild — runs build, lint, test
2. codeReview — spins up multiple Claude Code subagents to do the review
3. submitPr — creates PR on GitHub and waits for checks to complete
4. fetchPRFeedback — queries the PR for the status of all checks and all unresolved conversations (both bots like CodeRabbit and humans)

I built a small library to extract away the mechanics so the workflows themselves are declarative (highly experimental don’t copy this!). And I use existing typescript SDKs for interacting with github.

Composable workflow steps

Each step in the worfklow conforms to the following types. This makes it easy to compose steps, and to decouple declarative steps from generic infrastructure for running steps.

export function runWorkflow(steps: Step[]): void {
  executeWorkflow(steps).catch(handleWorkflowError)
}

export type Step = (ctx: WorkflowContext) => Promise<StepResult>

export type StepResult =
  | { type: 'success' }
  | {
    type: 'failure'
    nextAction: NextAction
    details: unknown
  }

A step looks like this:

export const verifyBuild: Step<CompleteTaskContext> = async () => {
  const result = await nx.runMany(['lint', 'typecheck', 'test'])

  if (result.failed) {
    return failure({
      type: 'fix_errors',
      details: result.output 
    })
  }

  return success()
}

I did look for existing libraries but didn’t find anything that seemed lightweight enough. Let me know if there is something lightweight and robust already available.

Claude Code SDK

We still need AI to perform the code review, and that can’t be done in pure code (you can invoke external services like CodeRabbit via CLI, but here we want to do a local code review with our own agent first).

Instead of the main Claude Code agent spinning up subagents. Now, TypeScript will orchestrate Claude Code agents like this:

import { query } from '@anthropic-ai/claude-agent-sdk'

const result = await query({
                  prompt: opts.prompt,
                  options: {
                    model: opts.model,
                    maxTurns: 50,
                    outputFormat: {
                      type: 'json_schema',
                      schema: z.toJSONSchema(opts.outputSchema),
                    },
                  },
                })

You pass in a prompt and your options and you get a result back. The outputFormat is extremely useful here. You can pass a json schema and the SDK will ensure the response from Claude is valid against the schema.

So my code review step looks like this:

const reviewerNames = ['code-review', 'bug-scanner']

const results = await runReviewers(reviewerNames, filesToReview, ctx.reviewDir, ctx.taskDetails)

async function runReviewers(
  names: readonly string[],
  filesToReview: string[],
  reviewDir: string,
  taskDetails?: {
    title: string
    body: string
  },
): Promise<ReviewerResult[]> {
  return Promise.all(
    names.map(async (name) => {
      const agentPath = `.claude/agents/${name}.md`
      const basePrompt = await readAgentPrompt(agentPath)
      const reportPath = `${reviewDir}/${name}.md`

      const promptParts = [basePrompt, '\n\n## Files to Review\n\n', filesToReview.join('\n')]

      if (name === 'task-check' && taskDetails) {
        promptParts.push(
          `\n\n## Task Details\n\nTitle: ${taskDetails.title}\n\nBody:\n${taskDetails.body}`,
        )
      }

      const response = await claude.query({
        prompt: promptParts.join(''),
        model: 'sonnet',
        outputSchema: agentResponseSchema,
        outputPath: reportPath,
      })

The runReviewers method is based on a convention. It takes a list of reviewer names and for each one it looks in .claude/agents/ for a prompt matching the name which contains the review instructions.

Then it passes the prompt to the Claude SDK with the files to review and gets the output back in the valid JSON structure. You have to add instructions in the prompt to tell Claude to return the result in that format of course.

Workflow enforcement

One key point I think is worth mentioning is that when you automate your workflow, you don’t want Claude bypassing it and calling commands directly. That’s why hooks in Claude Code are important.

For example, I have these hooks that block Claude from directly running the gh cli tool and remind it of the correct dev workflow commands to run instead:

# Block direct git push - agents must use /complete-task workflow
if [[ "$command" =~ (^|[[:space:]])git[[:space:]]+push($|[[:space:]]) ]]; then
    jq -n '{
      "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "deny",
        "permissionDecisionReason": "Blocked: Direct git push bypasses required workflow. Use /complete-task command instead, which runs the complete verification pipeline (lint, test, code review, PR submission) and prevents orphaned changes."
      }
    }'
    exit 0
fi

# Block ALL gh pr commands - must use dev-workflow tools
if [[ "$command" =~ (^|[[:space:]])gh[[:space:]]+pr($|[[:space:]]) ]]; then
    jq -n '{
      "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "deny",
        "permissionDecisionReason": "Blocked: Do not use gh pr directly. Use:\n- /complete-task - Create/update PR, run reviews, submit, check CI\n- pnpm nx run dev-workflow:get-pr-feedback - Check PR feedback and status (mergeable?)"
      }
    }'
    exit 0
fi

Very rough

The ideas in this post are the latest evolution of my software development workflow automation. I am learning and evolving the process every week.

I’m not telling you to do this, I’m just sharing that this is the best approach I have found so far. Conceptually, putting the orchestration in real code and shelling out to LLMs only where they are truly needed makes sense. And in practice it seems to be working.

Maybe there are tools that solve this in a better way or maybe I just need to learn how to write better prompts.

But regardless of the implementation, one thing seems inevitable to me: we’re going to see the SDLC being automated in 2026.

Dev Workflows as Code was originally published in Nick Tune’s weird ideas on Medium, where people are continuing the conversation by highlighting and responding to this story.

I’ve been using Claude Code a lot for personal projects and work projects, and one of the most interesting aspects for me is shaping software development workflows. I think this is something we are all (or should be) thinking about and experimenting with right now.

It interests me because the workflows allow us to make AI behaviour more predictable and it allows us to bake quality and other personal and organizational conventions into our processes. I’m also seeing that it allows us to automate more so we can focus more of our efforts where we add the most value.

A few months ago I wrote about this but I’ve learned so much since then. I wanted to write another post to get all of this out of my head and structure my thoughts. And also to think about where this is heading and what will be different in 6 months and how to prepare for that now.

In this post I focus on the workflow. In the last post I focused on concrete techniques I’m using for baking quality into the process

Task Implementation

Recently, I’ve been iterating a lot on the task implementation part of the workflow. I define this phase as from the moment where an agent/develoer starts working on a ticket (assigns it to themselves, marks it as in progress) until there is a pull request open ready to be merged (or requiring feedback).

On my personal project, I’ve been experimenting with the goal of 100% AI-generated code but with the highest code quality possible. I don’t know how it will turn out, but the lessons learned will be valuable.

In this context, my workflow defines the agent’s goal as:

Work through the entire lifecycle autonomously until you have a mergeable PR or are blocked. Present the user with a completed pull request that is green and ready for review.

And the workflow looks like this:

What I’m trying to achieve here is that the agent will start working on a ticket and notify me once the whole pull request is finished, meets all of our quality standards and conventions, and is ready for me to review.

I think in 2026 we’ll see better tooling for orchestrating these types of workflows. Tooling that provides more determinism for gluing together different steps and processing structured inputs and outputs.

Shell scripts vs AI commands

In the workflow above, there are a mix of Claude commands (i.e. prompts) and bash scripts. Where possible, I try to use bash scripts for deterministic behaviour. For example, starting a task involves creating a feature branch in a standard manner and marking the item as in progress.

For the /complete-task workflow, this is a prompt and uses subagents to handle different steps. It requires more interpretation and isn't so easy to automate with bash scripts. Although, there are certain parts that are automated with bash scripts like querying GitHub to get pull request feedback.

I use subagents for 2 reasons:

• when the main agent is working on a task, the context window will be full and it is less likely to follow instructions. A dedicated subagent with a fresh context is more likely to follow the instructions (it has a single clear focus)
• it won’t pollute the main agent’s context window

Task Completion

At the moment, task completion is the most complex part of my workflow. I wanted to use a subagent to orchestrate this process, but subagents can’t spawn other subagents.

/complete-task
    │
    ▼
Main agent runs pipeline directly
    │
    ├── Verify gate → FAIL → return to main
    ├── code-review subagent → FAIL → return findings + next steps
    ├── Task-check subagent → FAIL → return issues
    ├── submit-pr subagent → captures output
    ├── Check reviewDecision (CHANGES_REQUESTED = not mergeable)
    ├── Address ALL CodeRabbit feedback (comments + nitpicks)
    ├── Re-run submit-pr if fixes made
    └── Return SUCCESS with PR ready to merge

The first step is to run build, lint, test locally. Then it will run a local code review using the code review subagent and in parallel it does task-check. This is basically a QA - does the work that has been done match the requirements that are in the task (in this case the GitHub issue)

If both of those succeed, the next subagent will push the changes to GitHub and create a pull request. It will use the GitHub cli to wait for all of checks to complete:

gh pr checks --watch --fail-fast -i 30

Currently I have some general CI checks and CodeRabbit and SonarQube that automatically review all pull requests. So if any of these checks fail, or request changes, or leave any nitpicks, the process instructions the agent to automatically fetch them using the GitHub GraphQL API.

gh api graphql -f query='
  query($pr: Int!) {
    repository(owner: "owner", name: "repo") {
      pullRequest(number: $pr) {
        reviewDecision
        reviewThreads(first: 100) {
          nodes {
            isResolved
            comments(first: 1) {
              nodes { body }
            }
          }
        }
      }
    }
  }' -F pr=$PR_NUMBER

At this point, if anything so far has failed, the agent is empowered to autonomously fix the issues. It is instructed to keep working and addressing feedback (from local checks or on the CI) until the PR is mergeable or it is stuck or needs some help.

It did take me a while to get this all setup, and I’m still improving the process, so there is a cost involved in setting all this up. But I’m at a point where it’s working and justifies the effort.

Single source of truth for conventions

Different AI agents and different tools are involved in this workflow. And it’s important that they are all aligned on the same conventions. Otherwise they might end up going round in circles and wasting time (local review says one thing and then CodeRabbit flags it as a problem for example).

So my recommendation is to have a single source of truth for your coding standards and conventions not coupled to any AI tool.

I put them in /docs/.... And then any agent or tool that is writing code or reviewing it can reference these documents — the agent writing the code, the local agent reviewing the code, and tools like CodeRabbit will all be aligned to your same conventions.

My coderabbit.yml looks like this:

knowledge_base:
  code_guidelines:
    enabled: true
    filePatterns:
      - "docs/conventions/software-design.md"
      - "docs/conventions/anti-patterns.md"
      - "docs/conventions/testing.md"
      - "docs/conventions/standard-patterns.md"
      - "docs/conventions/codebase-structure.md"
      - "docs/architecture/overview.md"
      - "docs/workflow/code-review.md"

One other recommendation is to point your code review tools and agents at your ADRs. I’ve actually seen an example of this where the code review bot provided a PR comment explaining that the implementation didn’t align with an ADR and referenced the ADR specifically. I don’t have ADRs in the example above (but I will add it).

Build quality in, continuous improvement

Once you have a workflow and you have your context (your conventions, architecture docs, ADRs, and coding standards that all agents reference), then things get really exciting. The process of continuous improvement begins. This is where I’ve been having a lot of fun.

The mindset I have is, “how can I improve the process so that any error or manual intervention that I’ve had to make can be avoided next time.” For example, when CodeRabbit or SonarQube identifies an issue, I try to research linting rules. Can I find a linting rule that will catch this problem locally before it gets to these tools?

If linting rules aren’t possible then I look at ways to add this to the coding conventions or architecture documentation so that either the main agent or the local code review will catch it first.

On the contrary, I also wonder if at some point I will remove some of these checks. Maybe I will skip the local checks and just let the agent build the feature and create the PR and let all of the review happen there. If I can optimize the local development cycle so that it produces high quality to spec, then we speed up the overall process by having fewer checks. I’m not there yet, I still like having the local checks and not relying on CodeRabbit 100%.

Key challenges for teams and organizations

Based on my learnings and trying to take all these ideas and see how they apply to modern organizations, there are a few intersting challenges that we’ll have to face.

Defining standards

The first challenge is around consistency and standards. I think AI-assisted workflows will work best when there are more standards and clearer guidelines to follow. Some teams already do this, but some teams have many implicity conventions and different team members prefer different principles and patterns.

I think teams that excel are going to be more explicit with their coding standards and conventions. I.e. the context.

Continuous improvement mindset

Another challenge I see is the continuous improvement aspect. For engineers who like writing code and building systems, it could be a big change in mindset. Now, a key part of the job is to automate software development and identify mistakes or improvement opportunities so that AI produces better code and architecture.

Rather than writing code, I think it might be more that we need to think about “how can we improve the workflow and context so that we don’t need to manually write this line of code”. Software engineering might be more workflow + context engineering.

Organizational vs team conventions

A challenge we always face is deciding at what level a convention applies. Where do we standardize on tech stacks and architecture patterns and where do teams have freedom to go in their own direction. And this will definitely be a big challenge for defining workflows.

Allowing teams to have freedom could be crucial, as they discover new tools and techniques that others can benefit from, or are more suited to their local context. Equally, having some standard choices around conventions and tooling can bake in a minimum level of good practices and improve efficiency.

As a starting point, I think a good middle ground is always to be principles-driven. So you might define an AI-development principle such as “Each team must have documented coding standards and ADRs that are accessible to all AI agents and code review tools”. Each team can then define their own standards and use their own tooling to satisfy this principle.

Planning and Task Breakdown

You might have noticed in the task workflow table earlier that I have steps for managing PRDs and creating tasks. This is an important part of the process that I didn’t dive into: the phase before implementation where you break down requirements into actionable tasks.

I work with a PRD specialist agent to create the PRD first. This agent goes through a structured lifecycle (draft, planning, approved) and asks probing questions rather than just transcribing what I say. Once the PRD is approved, I activate it and use /create-tasks to break it down into specific implementation tasks.

This phase is actually really important because the quality of the task definition directly impacts the quality of the implementation. When you provide the AI with clear instructions, specific acceptance criteria, and edge cases to consider, the chances of getting the output you want go up significantly.

My /create-tasks command enforces a 10-section structure for every task including deliverable, context, traceability to PRD requirements, acceptance criteria, edge case scenarios, implementation guidelines, testing strategy, and verification commands. If any section can't be completed with specific details, the task gets rejected. This structure forces clarity upfront and ensures the implementing agent has everything it needs.

I built this myself because I wanted to learn from the ground up, but there are spec-driven frameworks out there that handle this phase. If you’re just getting started, it might be worth looking at what already exists rather than rolling your own.

These are just my personal learnings

I’m not saying these are the best practices. I don’t really know what the best practices are. And anyway, things are changing so quickly that all of this will be out of date soon anyway.

These are just my personal learnings from trial-and-error and also looking at what other people are doing. I hope you found some of this useful, and if you have any suggestions or ideas that are missing I would love to hear it. I’m in full learning mode.

Thanks to everyone who has already shared feedback with me. Every time I write a post or share an idea on LinkedIn I receive ideas and insights from other people which is really helping me.

I’ve learned a lot from many sources but Paul Hammond and Simon Martinelli regularly provide feedback on LinkedIn and I’m always checking what they’re upto, so special mention to them and I definitely recommend following them.

Coding Agent Development Workflows was originally published in Nick Tune’s weird ideas on Medium, where people are continuing the conversation by highlighting and responding to this story.

There are a few basic techniques you can use to increase the quality of code produced by AI coding assistants. These are easy techniques you can apply to any codebase so I highly encourage you to spend a little time setting them up.

The techniques fall into three broad groups

• Rules: define coding quality and standards
• Reviews: feedback loops to verify produced output
• Blocks: hard checks to ensure rules and reviews aren’t bypassed

In this post I’ll share the real examples from my open source side project living-architecture.

Rules

Rules define what code quality means in your codebases. I bundle standards, principles, and conventions all under this generic umbrella.

Lint rules

Lint rules are one of the most effective techniques for baking in code quality since they are easy to enforce and many rules already exist, plus it’s easy to create your own.

My lint config contains rules like the following…

Type safety
I’ve banned any and as type assertions. Claude Code loves to use these a lot and can’t be trusted with them. I never use them myself anyway, there’s always a better alternative.

// No any types
'@typescript-eslint/no-explicit-any': 'error',
'@typescript-eslint/no-unsafe-assignment': 'error',
'@typescript-eslint/no-unsafe-member-access': 'error',
'@typescript-eslint/no-unsafe-call': 'error',
'@typescript-eslint/no-unsafe-return': 'error',

// No type assertions - fix the types instead
'@typescript-eslint/consistent-type-assertions': [
    'error',
     { assertionStyle: 'never' },
 ],

// No non-null assertions - handle errors properly
'@typescript-eslint/no-non-null-assertion': 'error',

Code complexity
I’ve set a maximum code complexity per-function as 12 , maximum level of indentation as 3, and a maximum file size of 400.

When Claude hits these limits, it forces it to think about how to make the code more modular and it usually does a good job.

Without these limits Claude will absolutely create highly nested code and files with 1k+ lines.

// Complexity limits
'max-lines': [
    'error',
    { max: 400, skipBlankLines: true, skipComments: true },
 ],
 'max-depth': ['error', 3],
 complexity: ['error', 12],

Naming
I observed that Claude would use a lot of generic naming like helper and utils . It seems so lazy and just defaults to these generic names even when finding more accurate names isn’t hard.

So I use lint rules to ban the worst offenders. And it works. Claude hits the lint rule and has to think of a better name, and it always finds something more appropriate.

// Ban generic folder imports (not lib - that's NX convention)
'no-restricted-imports': [
    'error',
        {
          patterns: [
            {
              group: ['*/utils/*', '*/utils'],
              message: 'No utils folders. Use domain-specific names.',
            },
            {
              group: ['*/helpers/*', '*/helpers'],
              message: 'No helpers folders. Use domain-specific names.',
            },
            {
              group: ['*/common/*', '*/common'],
              message: 'No common folders. Use domain-specific names.',
            },
            {
              group: ['*/shared/*', '*/shared'],
              message: 'No shared folders. Use domain-specific names.',
            },
            {
              group: ['*/core/*', '*/core'],
              message: 'No core folders. Use domain-specific names.',
            },
            {
              group: ['*/src/lib/*', '*/src/lib', './lib/*', './lib', '../lib/*', '../lib'],
              message: 'No lib folders in projects. Use domain-specific names.',
            },
          ],
        },
      ],

Test coverage

In my vitest configs I set test coverage to 100%. Sometimes you might need to set more granular rules but I recommend starting out with 100 for everything and iterating from there.

coverage: {
    reportsDirectory: './test-output/vitest/coverage',
    provider: 'v8' as const,
    exclude: ['**/*test-fixtures.ts'],
    thresholds: {
      lines: 100,
      statements: 100,
      functions: 100,
      branches: 100,
    },
},

Claude will often miss edge cases, even with detailed planning. 100% coverage requirements help to catch them. They don’t guarantee perfect tests but it’s better to have these thresholds than not having them.

Standards and conventions

For other coding standards, principles and conventions I have a /docs/conventions folder:

Then these are referenced in the main CLAUDE.md so that Claude knows when to read them.

## Code Conventions

When writing, editing, refactoring, or reviewing code: 

- always follow `docs/conventions/software-design.md` 
- look for standard implementation patterns defined in `docs/conventions/standard-patterns.md`
- avoid `@docs/conventions/anti-patterns.md`

The automatic code review agent enforces these conventions (see `./claude/automatic-code-review/rules.md`)

Code quality is of highest importance. Rushing or taking shortcuts is never acceptable.

## Testing

Follow `docs/conventions/testing.md`.

100% test coverage is mandatory and enforced.

Reviews

For anything that is not enforced by a tool (i.e. lint and test coverage) I recommend setting up reviews where a separate, specialist agent will review the work that has been done and provide feedback to the main agent.

In living-architecture I have fully automated reviews by a second agent that take place before the human in the loop is asked to review the work.

Automated code review

In a previous post I mentioned the automatic code review technique I had setup with Claude Code hooks. In living-architecture I have found this to be extremely useful.

The automatic code review runs every time Claude has finished. It automatically kicks in. In living-architecture I set up the automatic code review to re-inforce the same conventions that are in CLAUDE.md

Architecture, modularity check
Check all production code files (not test files) against the following conventions:

Read @/docs/architecture/overview.md Read @/docs/conventions/codebase-structure.md

Ensure that all code is in the correct place and aligns with boundaries and layering requirements. Look at each line of code and ask "What is the purpose of this code? Is it related to other code? Is it highly cohesive? Should it really be here or would it fit better somewhere else?"

Coding Standards
Check all production code files (not test files) against the following conventions:

Read @/docs/conventions/software-design.md 
Read @/docs/conventions/standard-patterns.md

Claude will not always follow standards and guidelines, no matter how great your prompts and CLAUDE.mdfile are. But with a dedicated agent focused on review fewer things slip through the net the chance of the standards being applies increases substantially.

Whenever you see bad code, add the convention or pattern to one of the files and next time the reviewer will automatically pick it up.

Functionality review

Similar to auto code review I setup an auto task check:

• /docs/workflow/task-workflow.md that tells Claude to run the task-check command when it’s finished a piece of work
• CLAUDE.md references /docs/workflow/task-workflow.md
• task-check compares the work done to the requirements

This is where defining requirements is crucial. My approach is to write PRDs and then break them down into tasks stored in task master.

So when I start a new session I say “next task” and Claude picks the next ticket and marks it in progress and starts working on it. Then, the reviewer agent knows what to check.

It’s also a good idea to use code quality tools like CodeScene, Sonarqube and CodeRabbit. The tools can built in your CI pipeline and also provide local feedback to your coding assistants via MCP.

In living-architecture — I use SonarQube and CodeRabbit.

Blocks

Whatever rules and guidelines you try to put in place, your AI assistant is going to try and find ways around them. So here are some simple techniques you can use to prevent that.

git hooks

I highly recommend using git hooks. I do a full lint, typecheck, test verification for the whole monorepo on each commit.

NX has an effective caching system which means the performance of this is quite reasonable for the high level of confidence it provides.

Prevent dangerous operations and file modification

All of the rules you set up can be bypassed AI. For example, when the git hooks fail Claude will always try to use --no-verify to bypass checks.

You can use Claude hooks to prevent these dangerous commands:

"PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/block-dangerous-commands.sh"
          }
        ]
      }
    ]

I also recommend setting up file modification rules so that AI cannot modify your lint or test coverage configuration files.

Branch protections

If you want to enforce that all commits to main go through your CI process then it’s good to setup branch protections on your repository.

In living-architecture pushes to main are forbidden and AI must satisfy SonarQube and CodeRabbit checks. I have my CodeRabbit setup to run the same code conventions that Claude will check locally:

knowledge_base:
  code_guidelines:
    enabled: true
    filePatterns:
      - "docs/conventions/software-design.md"
      - "docs/conventions/anti-patterns.md"
      - "docs/conventions/testing.md"
      - "docs/conventions/standard-patterns.md"
      - "docs/conventions/codebase-structure.md"
      - "docs/architecture/overview.md"
      - "docs/workflow/code-review.md"

With this approach, even if someone doesn’t run Claude or do the checks locally, the CI will ensure that those checks happen.

For consistency, I try to have a single source of truth for my rules and conventions, and then each tool like CLAUDE.md or .coderabbit.yml just points to the source of truth.

Both SonarQube and CodeRabbit are free for open source projects.

Code Quality Foundations for AI-assisted Codebases was originally published in Nick Tune’s weird ideas on Medium, where people are continuing the conversation by highlighting and responding to this story.

A well-crafted system prompt will increase the quality of code produced by your coding assistant. It does make a difference. If you provide guidelines in your system prompt for writing code and tests, coding assistants will follow the guidelines.

Although that depends on your definition of “will follow”. If your definition is “will follow often” then it’s accurate. If your definition is “will follow always” or even “will follow most of the time” then it’s inaccurate (unless you’ve found a way to make them reliable that I haven’t, please let me know).

Coding agents will ignore instructions in the system prompt on a regular basis. As the context window fills up and starts to intoxicate them, all bets are off.

Even with the latest Opus 4.5 model, I haven’t noticed a major improvement. So if we can’t rely on models to follow system prompts, we need to invest in feedback cycles.

I’ll show you how I’m using Claude Code hooks to implement automatic code review on all AI-generated code, so that code quality is higher before it reaches the human in the loop.

A code example that demonstratest the concepts discussed in this post is on my github: https://github.com/NTCoding/claude-skillz/tree/main/automatic-code-review

All my posts are 100% human written — all mistakes (and em dashes) are my own

Auto code review for fast, semantic feedback

When I talk about auto code review in this post, I am describing a fast feedback mechanism intended to review common code quality issues. This will be run whenever Claude has finished making edits so it needs to be fast and efficient.

I also use coding assistants for detailed code reviews when reviewing a PR, for example. That will spin up multiple subagents and take a bit longer. That’s not what I’m talking about here.

The purpose of the auto code review is to reinforce what’s in your system prompt, project documentation, and on-demand skills. Things that Claude may have ignored. Part of a multi-pronged approach.

Wherever possible, I recommend using your lint and test rules to bake in quality, and leave auto code review for more semantic issues that tools can’t check.

If you want to set a maximum length for your files or maximum level of indentation, then uses your lint tool. If you want to enforce a minimum test coverage, use your test framework.

Semantic code review

A semantic code review looks at how well the code is designed. For example, naming. Does the code accurately describe the business concepts it represents?

AI will often default to names like “helper” and “utils”. But AI is also good at understanding the nuance and finding better names if you challenge it, and it can do this quickly. So this is a good example of a semantic rule.

You can ban certain words like “helper” and “utils” with lint tools (I recommend doing that). But that won’t catch everything.

Another example is logic leaking out of the domain model. When a use case / application service queries an entity and then makes a decision, it’s highly like your domain logic is leaking into the application layer. Not so easy to catch with lint tools, but worth addressing.

class RandomUseCase {
  ...
  
  const customer = repository.load(customerId)

  // query the domain then make a decision based on it's state. 
  // common anti-pattern. The customer entity should protect its invariants
  if (customer.isActive()) {
    customer.awardLoyalty(...)
  }
  ...
}

Another example is default fallback values. When Claude has an undefined value where a value is expected, it will set a default value. It seems to hate throwing exceptions or challenging the type signature and asking “should we allow undefined here?”. It wants to make the code run no matter what and no matter how much the system prompt tells it not to.

const paymentType = command.paymentType ?? 'bank-transfer' // Bad - we shouldn't guess or assume. But AI will do this a lot

const age = request.age ?? 18 // probably a bad default value

const effectiveDate = event.effectiveDate ?? new Date() // This is probably ok

const isEnabled = feature.enabled ?? false // This could be ok

You can catch some of this with lint rules but it’s very nuanced and depends on the context. Sometimes falling back to a default value is correct.

Building an auto code review with Claude hooks

If you’re using Claude Code and want to build an auto code review for checks that you can’t easily define with lint or testing tools, then a solution is to configure a script that runs on the Stophook.

The Stophook is when Claude has finished working and passes control back to the user to make a decision. So here, you can trigger a subagent to perform the review on the modified files.

To trigger the subagent you need to return the error status code which blocks the main agent and forces them to read the output.

⏺ Ran 1 stop hook
  ⎿  Stop hook error: 📋 CODE REVIEW REQUIRED

  Files modified since last review:
  - /.../src/features/flows/components/CodeLinkMenu/C
  odeLinkMenu.tsx

  INSTRUCTION: Use the Task tool with subagent_type "automatic-code-reviewer". Pass only the
  file list as the prompt. The agent will follow its configured review procedure. SHOW ALL
  FINDINGS TO THE USER.


⏺ automatic-code-review:automatic-code-reviewer(Review modified code)
  ⎿  Done (19 tool uses · 18.0k tokens · 52s)

⏺ Code Review Findings

  The automatic code reviewer found 3 violations related to domain modeling:

  Violations Found

  1. [DOMAIN MODELING] - CodeLinkMenu.tsx:6
    - Issue: filePath is a bare string primitive representing a domain concept. Should use a
  branded type like FilePath to enforce type safety.
    - Fix: Create a branded type type FilePath = string & { readonly __brand: 'FilePath' } and
  update the parameter to filePath: FilePath

I think it’s generally considered a best practice to use subagent focused on the review with a very critical mindset. Asking the main agent to mark it’s own homework is obviously not a good approach and it will use up context window.

The solution I use is available on github. You can install it as a plugin in your repo and customize the code review instructions or just use it as inspiration for your own solution. Any feedback is welcome, btw

In the example above you can see it took 52s. Probably quicker than me reviewing providing the feedback myself. But that’s not always the case, sometimes it can take a few minutes.

If you’re sitting there blocked waiting for review, this might be slower than doing it yourself. But if you’re not blocked and are working on something else (or watching TV), this saves you time because the end result will be higher quality and require less of your time to review and fix.

Scanning for updated files

I want my auto code review to only review files that have been modified since the last pull request. But Claude doesn’t provide this information the context to the Stop hook.

I can find all files modified or unstaged using git, but that’s not good enough.

What I do instead is to hook into PostToolUse by keeping a log of each modified file.

"PostToolUse": [
   {
    "matcher": "Write|Edit|MultiEdit",
    "hooks": [
      {
         "type": "command",
         "command": "${CLAUDE_PLUGIN_ROOT}/hooks/tools/automatic-code-review-plugin.sh log"
       }
     ]
   }

When the Stop hook is triggered, the review will find the files modified since the last review and ask the subagent to review only those. If there are no modified files, the code review is not activated.

Challenges with the stop hook

Unfortunately the stop hook is not 100% reliable for this use case for a few reasons. Firstly, Claude might stop to ask a question, e.g. for you to clarify some requirements. You might not want the auto review to trigger here until you’ve answered Claude and it has finished..

The second reason is that Claude can commit changes before the Stop hook. So by the time the subagent performs the review, the changes are already committed to git.

That might not be a problem and there are simple ways to solve it if it is. It’s just extra things to keep in mind and setup.

The ideal solution would be for Anthropic (or other tool vendors) to provide us hooks that are higher level in abstraction — more aligned with the software development worklow and not just low level file modification operations.

What I would really love is a CodeReadyForReview hook which provides all the files that Claude has modified — then we can throw away our custom solutions.

Let me know if you have a better approach

I don’t know if I’m not looking in the right places or if the information isn’t out there, but I feel like this solution is solving a problem that should already be solved.

I’d be really grateful if you can share any advice that helps to bake in code quality before the human in the loop has to review it.

Until then I’ll continue to use this auto code review solution. When you’re giving AI some autonomy to implement tasks and reviewing what it produces, this is a useful pattern that can save you time and reduce frustration from having to repeat the same feedback to AI.

Auto-Reviewing Claude's Code was originally published in Nick Tune’s weird ideas on Medium, where people are continuing the conversation by highlighting and responding to this story.