In your Claude Code session, point Soundings at one or more GitHub or GitLab compare URLs:

It reads the diffs, the commit messages, the PR and MR comments, and the repository documentation. Then it hands back one clear verdict (release, manual review, or no-go) and a report specific enough to act on: named files, named functions, concrete failure modes, and action items sorted by urgency. Before it starts, it asks where to save the report, unless you already said so:

A few minutes after you hit enter, the verdict shows up right in your session: the summary, the recommendation, and what drove it. The full report is the markdown file, written by the helper, ready to archive or to post where the ship decision happens.

The verdict follows a fixed policy: by default, any critical concern blocks the release and any high concern requires manual review. Every concern is a concrete claim you can go verify, so if the verdict feels wrong, you can check which concern caused it and whether that concern is true. You can also tighten the policy and block on high or even medium concerns for your most critical services.

There is nothing to deploy and no LLM API key to create: the analysis runs in the Claude Code session you already have. A small open-source Go helper does the deterministic work, borrowing the Git credentials you already use: a gh or glab login, or a platform token.

A run has three stages:

You can pass several compare URLs in one invocation, and they are analyzed together. A coordinated deployment usually spans repositories. The schema migration lives in one service, the code that depends on it in another. Per-repo CI can never see that interaction. A single analysis across all the repos of a deployment can, and compound risks are what Soundings hunts for. For a team shipping coordinated deployments every week, this is the feature that matters.

Soundings looks for the risk families you would brief a new release manager on:

Your session shows only the Summary section. The full report is in the markdown file. Here’s the top of one, from a demo analysis of a two-service release:

You can read the full demo report to see everything it contains.

Two findings from that report stand out. The critical one caught a database migration and the code using its new column shipping in the same release, a sequence the service’s own deployment rules forbid. Its action item: block the deployment and split the release, migration first, code second. The compound one caught a retry count raised from 2 to 5 in one file and a timeout raised from 200ms to 1s in another. Each change is fine alone. Combined, the worst case blows past the service’s 2 second SLO when the email service degrades. No single-file review connects those two lines.

The positives are evidence-based too, and just as specific. The same report credits the release for a feature flag guarding the new endpoint, an IF NOT EXISTS guard on the migration, a documented rollback path, and a gateway change verified compatible with both the old and new versions of the API behind it. That last one is only visible because the two repositories were analyzed together.

Here’s the complete setup on a machine that already runs Claude Code:

You need two things besides Claude Code: a Go toolchain, and a credential for each platform you analyze, either a gh or glab login or a GITHUB_TOKEN/GITLAB_TOKEN env var. That’s it. No LLM API key, no service account, no Docker image, no config file. At run time, Soundings picks the right credential for each platform and each GitLab host, so one invocation can mix github.com and any number of GitLab instances, and a token for one host is never sent to another.

Claude Code only updates plugins from its official marketplace automatically. Enable auto-update for claude-ichiba in the /plugin panel, or refresh it yourself from time to time:

Everything Soundings analyzes (diffs, commit messages, PR comments, repository docs) could have been written by anyone. Even your own release carries text you didn’t write: other people’s code, bot commits, comments from anyone with an account. So the design assumes every byte it fetches is hostile, and the protections are limits the AI cannot cross, not instructions it is asked to follow.

Two inputs make the analysis noticeably sharper.

A .soundings.md file in your repository root tells the analyst what the service is, how critical it is, and where the known risky areas are. Good candidates: the SLO your callers expect, deployment rules such as "migrations ship in their own release", rollback procedures, and links to your runbooks. That’s where the demo’s blocking concern came from: the analyst read the split-release rule in the repository’s own documentation and enforced it. Documentation linked from it is fetched too, SSRF-hardened and size-capped like every other fetch.

A /soundings note comment on a PR or MR hands the analysis context a diff cannot show:

Notes only influence the analysis when their author is the PR/MR author or an authorized approver, and that authorization is computed from the platform API, never guessed. Unauthorized notes are disclosed in the report but excluded from the analysis, so a random commenter cannot change the verdict. The demo report has an example: a commenter insists the release should ship regardless of the verdict, and the guidance table lists that note as ignored.

The full guide lives in the repo: Improving your release readiness analysis.

Soundings is the successor to Release Confidence Score, a tool I originally built at Red Hat, licensed under Apache-2.0. I extracted its core with the full git history preserved: the original commits, including the security hardening, are visible in the Soundings log. It is Apache-2.0 too, and the whole pipeline is open to inspection.

Everything in this post runs interactively, on a laptop, with a human reading the report. The next step is to remove the laptop. The entire pipeline (the skill, the isolated analyst, the helper) is designed to also run headless: a containerized Claude Code session analyzing a release unattended, as a step of the release process itself, delivering its report where the ship decision is made. And because the verdict is computed rather than written, it can serve as a gate in a continuous delivery pipeline: a clean verdict promotes, anything else stops the line and hands the decision back to a human, with the report already explaining why. That’s why a normal run already needs no permission prompt, and why the injection containment doesn’t rely on a human watching: the guarantees that make Soundings safe on your laptop are exactly the ones an unattended run needs. The only thing a headless run has to provide is where to write the report, since nobody is there to answer the question.

I’m also exploring how to port Soundings to Codex. The split at the heart of the design, code for the deterministic work and an isolated agent for the reading, is not specific to Claude Code. Stay tuned.

Soundings is under active development, and feedback directly shapes what changes next: issues and ideas are welcome on the repository.

Take soundings before you ship!

A unit test can assert an exact outcome because the code under test is deterministic: the same input produces the same behavior. An LLM is not deterministic. Run it twice on the same input and you may get different words, sometimes different decisions. You can’t assert equality on that, so an eval asks questions about the AI’s answer instead: "Is this claim accurate?", "Did it violate a stated rule?".

Evals started in research labs, as benchmarks for comparing models (Stanford’s HELM is a good example). The name caught on in 2023, when OpenAI open-sourced its Evals framework. This post follows that framework’s core idea: write your own evals for your own use case.

Any eval suite needs cases and a grader, and, if your product carries state, an environment to run them in. Mine started simple:

The cases come from your product’s promises: write one for each rule it must follow and each kind of request it must handle.

My plan was just as simple: write the cases, let the judge grade the answers, fix the plugin until everything went green, then make that green a gate no release could skip. This plan looked solid until the judge started grading.

I wrote the first version of the suite in Go, like every other tool in the repo. It worked, but I didn’t like owning an eval harness, the code that runs the suite, when so many already exist. So I gave Promptfoo, one of the most popular eval frameworks, a real chance and ported the suite to it a few different ways. All of them worked, but none beat the plain Go runner they were meant to replace.

Frameworks offer real machinery: assertions, built-in AI graders, and test matrices. But the hard part of my suite, about 450 lines, was state: seeding a user profile on disk before each case (the plugin keeps one to remember what each developer already knows), isolating each run in its own throwaway home directory so runs can’t see each other’s files, handing the judge the exact catalog files to check answers against. Every port kept all of that code and simply moved it into the framework’s hooks. All Promptfoo could take off my hands was the loop that runs each case and collects results, a few dozen lines of Go, at the price of a second toolchain and a config layer.

Before adopting an eval framework, count the lines it would actually save you. If your product is stateless, prompt in and text out, a framework will save you real time. Agent-focused harnesses like the UK AI Security Institute’s Inspect even host the isolated test environments for you. But no framework knows your product’s rules, so the fixtures, the facts the judge grades against, and the checks are still yours to write.

One of the first bugs my evals caught was in the judge, not the plugin.

The plugin taught a real, documented Claude Code feature that shipped recently. The judge flagged it as fabricated. The judge’s training data was older than the feature, so it was grading 2026 answers with frozen knowledge, confidently calling the truth an invention.

That turned into a rule the suite still enforces: the judge only fails an answer based on facts it was handed, never on facts it remembers. Handed means literally pasted into the judge’s prompt: the list of plugins that exist, the documentation behind each capability, and the files in the fixture project. An instruction like "you know what Claude Code supports" is a mistake, because the judge’s knowledge is frozen at training time. Same goes for any fact your judge couldn’t have learned in training: your internal rules, your data, whatever shipped last month.

Stale knowledge doesn’t only hide in the judge’s training. One of my tests described, in prose, what one of the plugin’s data files should contain. That file changes weekly by design, and the test failed three correct plugin answers in a row. Prose descriptions go stale the moment the file changes, so now the judge gets the file itself instead of my description of it.

Handing the judge files fixed what it knew. It did nothing for how it reasoned.

It took me weeks to check the judge itself, because a broken judge doesn’t look broken. Its wrong verdicts look like product failures, so every red result sent me to fix the plugin instead of questioning the grader. Eventually I blind-labeled a sample of the judge’s verdicts: reviewer agents read each answer and formed their own verdict before seeing the judge’s, and I settled the disagreements myself. I used AI to audit the AI. The textbook version has a human label everything. Letting AI reviewers do the first pass is what made it a couple hours of my time instead of a day. Measuring and correcting a judge this way is called calibrating it.

The judge turned out to be right 75 percent of the time, meaning one verdict in four was wrong.

My own spec, the written rules for how the plugin must answer, required every recommendation to carry a "do it now" offer, and the judge failed answers for containing exactly that offer. It passed an answer that skipped a required warning label, because a similar-looking phrase nearby fooled it. And it excused some failures by citing exceptions that nobody had written anywhere. Every error came from one sentence in the judge’s instructions or one ambiguous sentence in my spec, and every fix was one sentence long.

False greens, answers that broke the rules but passed anyway, were the expensive kind. A wrong failure gets investigated. A false green stays quiet: nobody checks a passing test, so the bug survives. The couple hours I spent calibrating earned more trust in the suite than anything else in the project, and I did it two weeks late. Two days after the one-sentence fixes, the same blind check hit 100 percent on a fresh sample of 24 verdicts.

The judge had misled me more than once by then, so I got suspicious of the one component I had never questioned: the fixture project, the sample codebase Claude had generated at the start. That suspicion was justified.

The fixture’s own docs claimed it was a web service built with Express, a popular Node.js framework. It had no routes and no server, and the Express dependency sat unused. One test asked the plugin to document "our orders endpoints", endpoints that didn’t exist. One earlier failure I’d blamed on the plugin was actually the plugin correctly catching the fixture’s false claim, and getting punished for it. Better yet, Claude had left a comment in the fixture’s source code: "eval cases need real paths to ground against". In plain words: a note that this codebase exists to be tested. Every test run, the plugin under test could read that it was inside a test. That matters more than it sounds: models often detect when they are being evaluated, and may behave differently when they do. The fix is two cheap checks. Verify every claim the fixture makes about itself against its own files, and search it for anything that admits it’s a test.

By that point the judge had invented exceptions, my spec had proven ambiguous, and the fixture had lied about what it was. All three failures shared the same shape: something that sounded right until it was checked.

Around week four I got tired of iterating: twenty-ish pull requests, each fixing one eval failure, and some introducing regressions. I told Claude there has to be a better approach.

The audit that followed found what I should have seen earlier. Most failures lived in one layer: the judge interpreting prose. A few checks skipped the judge entirely, plain code like greps and file comparisons, and they’d never produced a wrong verdict.

That’s when I realized I didn’t need to make the judge better, I needed to rely on it less.

So I gave the plugin a receipt to append to its answers: one HTML comment, a machine-readable summary of what it just did.

Users never see it: the plugin only emits the receipt when an environment variable enables it, and only the eval runner sets that variable. The fields are the plugin’s own vocabulary: the mode it ran in, the goal it classified, the move it recommended, and the surprise, a bonus capability it taught along the way. The eval runner reads it, and suddenly the hard questions become string comparisons. Did it classify correctly? Just check if the goal equals "debugging". Did it re-offer the capability the user declined? Just grep for it. Same verdict every time.

The judge didn’t disappear. A few cases genuinely need judgment, like the fabrication trap: ask for a feature that doesn’t exist and check that the plugin says so instead of playing along. Everywhere else, the judge now answers exactly one question: does the answer match its receipt? That one still needs a judge, because a model could write a receipt claiming one thing while the answer does another, and only a reader can catch the mismatch. But one question is a far easier job than before, when my written expectations asked the judge to verify over a dozen separate things per answer. A calibrated judge scores well, but only for a moment. New cases can reintroduce the old biases, and I would have to keep re-checking it forever. A string comparison never needs calibrating.

One rule in my plugin says: never mention a capability the user has declined. One test checks it. The gate runs every case three times per release, because a single run can pass by luck, and this test kept failing for two weeks, at first roughly one run in three.

Six fixes lowered the failure rate, but none reached zero. The model kept finding new sentences for the same leak, and at one point the investigation revealed why: another of my own rules was demanding the model justify its choice, and the only honest justification named the declined capability.

When a model keeps violating an instruction in creative new ways, look for the second instruction rewarding it.

The last lesson is the one I resisted longest.

Even after resolving the rules conflict, a residual failure rate remained: about 15 to 20 percent, stable, measured across dozens of individual runs. What should a release gate do with a test like that, when no prompt engineering can remove the failures?

Failing every release would be honest but useless. It would block a third or more of releases without surfacing anything new. Retrying until green would be worse than no test at all, because a green earned by retries just means I got lucky. So I split tests into two kinds:

I made the suite compute each flaky check’s baseline from the last five runs and ask a boring statistical question: is today’s failure count surprising, given the known rate? The idea is anything but new: Google was already treating its known-flaky tests this way back in 2016. Bad luck within the rate still passes, with a printed warning saying so. A genuine regression stays red. The test that blocked two releases became a monitored number that has not caused a crisis since.

Eight things I’d tell myself a month ago:

I’m one month into evals, and still learning. It took me most of that month to stop fixing failures that don’t matter. I worked through all of it with Claude Fable 5, and we checked every claim in this post against the suite’s code and run logs. The whole suite is open source if you want to see any of it for real.

If you’ve built evals for your own product, or you’re about to, I’m curious how it compares: share your experience, tips, or corrections in the comments.

Say a CVE just dropped against a library you depend on:

The mentor keeps a small markdown file at ~/.ai-mentor/profile.md, one line per capability, marked shown, adopted or declined:

This one tells the mentor: never explain plan mode or hooks to this engineer, open the next session by asking whether the deep research demo stuck, and never bring up fan-out again. It does not re-teach what it showed you last week, it skips what you already use, and it drops anything you declined.

The profile is machine-local and never committed, and it never leaves your machine except as context inside your own Claude sessions. You can edit or delete it whenever you want. A hand edit always wins over anything the mentor inferred. There is no account and no setup.

This is also why the mentor becomes more useful over time: every session starts from what you already know and reaches for the next thing you don’t.

Everything so far started from a problem you brought, which the plugin calls problem mode. Growth mode works in the other direction: invoke the mentor bare, and it finds something worth teaching on its own.

Depending on what it finds in your setup and your profile, it teaches the most valuable capability you’re not using yet, follows up on the last thing it showed you, or opens with what shipped since you last checked.

This also changes how you stay up to date. Following Claude Code means tracking changelogs, release notes, videos, tutorials and blog posts, and nobody sustains that alongside a day job. The mentor collapses all of it into a single interaction, and it only ever shows you the part that matters to you.

Under the hood, a playbook for each of 24 engineering goals (debugging, code review, refactoring, migration, incident response, performance, security, and so on) ranks 46 approaches. Most of them are technique deep-dives, and the rest are verified records of external tools such as the Claude Code GitHub Action and hands-on-validated plugins from Anthropic’s official marketplace.

Two parts of the catalog are worth mentioning separately.

First, it also serves people building AI, not just people using it. Four goal categories cover building AI agents, MCP integrations, skills and plugins, and LLM-powered product features, backed by dedicated catalog entries for the Agent SDK, MCP development tooling and LLM eval methodology. If your team is shipping an AI feature, "what’s the right approach here?" is a mentor question too.

Second, beyond the promoted set, the full official plugin marketplace (around 250 plugins) is available as a lookup directory. Name a technology in your problem, Quarkus or Terraform or Grafana, and the mentor greps the directory and surfaces the purpose-built plugin along with its install command. Every entry is labeled with how far it was verified: hands-on (installed and exercised), desk-checked (reviewed but not exercised), or caution (a built-in does it better, or there is a sharp edge to know about).

Claude already knows a lot about Claude Code, so why install a plugin instead of asking "what’s the best AI approach for debugging this?"

Because a model answering from memory is fine on average and unreliable in the details. Claude Code changes every week, so any model’s memory of it has gaps, and a model asked about a gap doesn’t say "I don’t know". It fills the gap with a plausible guess.

A catalog loses its value the moment its content stops matching reality, so most of the engineering in this project went into the pipeline that keeps it accurate:

The pipeline also runs on the same capabilities the catalog teaches: the maintenance passes are headless Claude sessions on a weekly schedule, so the plugin that recommends AI workflows is itself maintained by one.

Installation is three lines in Claude Code, no cloning and no file editing. The first line adds my plugin marketplace, claude-ichiba, and the next two install the plugin from it:

Then bring it a real problem, or bring nothing and let growth mode pick the lesson:

You don’t have to remember to call it either. If you ask something mentor-shaped in a normal session, like "what’s the best way to use AI for this?", Claude invokes it on its own.

Claude Code disables auto-update for third-party marketplaces by default, but this plugin ships updates regularly, because the catalog tracks a tool that changes weekly. Either enable auto-update once (/plugin → Marketplaces → claude-ichiba), or refresh manually whenever you want the latest catalog:

If you try it, start with the problem you are actually dealing with today. The plugin did its job when the answer contains something you didn’t know existed. And when it doesn’t, tell the mentor: it records what you already know and does better next time.

AI Mentor is deliberately Claude Code-first, so every recommendation can be verified against one tool’s current reality instead of being vaguely right about five tools. Support for other Agent Skills-compatible tools may come later.

I’m also considering the community plugin marketplace, which holds more than two thousand plugins of very uneven quality. If it joins the catalog, it will be through a strict selection: a small set of proven, actively maintained plugins, carrying the same trust tiers as everything else.

Everything is open source under Apache-2.0: the catalog, the playbooks, the verification tooling and the eval suite all live at github.com/gwenneg/ai-mentor. Issues and pull requests are welcome, especially reports of anything the mentor got wrong.

A Claude Code plugin is not a passive dependency you import. Installing one lets the author run code on your machine, at every session start and end, with no per-update review. Hooks can run shell scripts, but they can also execute pre-compiled binaries shipped in the plugin repo. Git preserves the executable bit, so a binary committed with chmod +x is ready to run the moment Claude Code fetches the plugin. No additional permission step on the user’s machine. As of this writing, Claude Code shows no diff when plugin hooks change and asks for no re-approval. There is no plugin signing, no checksum verification, no integrity check in the install path. That is a lot of trust to hand someone.

So the security bar for publishing a plugin is closer to running a software-update service than shipping a package. Every design choice in this post follows from that.

A plugin’s source field in marketplace.json tells Claude Code where to fetch the code. The three options (branch, tag and SHA) carry very different risks.

Three fields in each marketplace plugin entry control version detection, code pinning, and release traceability:

Both version and sha must change together on every release: a version bump without a SHA bump ships the same code, and a SHA bump without a version bump is invisible to Claude Code’s update mechanism.

A Claude Code marketplace is a JSON catalog that lists plugins and tells Claude Code where to fetch them. When the marketplace and the plugin share a repo, source is typically a relative path or a self-reference. That ties the plugin’s development to the marketplace’s. Every plugin commit is a marketplace commit. Every collaborator who can touch a plugin can also touch the catalog.

Splitting gives you:

I built a release pipeline for Claude Code plugins around two repos, both open source: claude-ichiba (Japanese for marketplace) is the catalog, and togi is the friction-capture plugin.

None of the pipeline complexity surfaces to users. Their side stays simple. Install with:

And update with:

This setup is the best I could do with what Claude Code and GitHub offer today. It’s not airtight.

This pipeline won’t solve what Claude Code hasn’t built yet. But it closes every gap I could find, and it’s yours to fork.

Plugin consumers: verify what you run. Authors: make that easy.

Model selection. First point: free. Second point: when did you last reach for Haiku?

Pick the right model for your task:

In interactive sessions, use /model to switch. In skills and agents, set it in frontmatter.

Dig deeper: Models pricing, Model configuration, Skill frontmatter, Sub-agent frontmatter

Yes. Claude is writing a dissertation about your variable renaming.

Thinking tokens count as output tokens. The priciest kind. A single request can burn tens of thousands of them. For a complex architectural decision, worth every token. For "add a missing semicolon," not so much.

In interactive sessions, use /effort low or /effort medium for straightforward tasks, and /effort high when it actually matters. In skills and agents, set it in frontmatter so nobody has to remember.

Dig deeper: Models pricing, Effort configuration, Skill frontmatter, Sub-agent frontmatter

A lot. The fix is simpler than you think: be specific.

Claude starts by figuring out what your codebase even is. That means reading files until it has enough context to act. And every file it reads stays in context, getting re-sent with every follow-up message. You’re paying for that exploration whether you asked for it or not.

Specificity isn’t just for interactive sessions. In skills and agents, every word in the spawn prompt loads on top of everything the agent auto-loads, from turn one. Vague instructions are just as expensive there.

Free points. You’re welcome.

Impressive documentation. Expensive documentation.

Everything in CLAUDE.md loads at session start and gets re-sent on every single request, whether it’s relevant or not. That beautifully written section explaining the history of your repository pattern? Claude reads it before fixing a typo. Every. Single. Time.

Dig deeper: Path-specific rules, Extend Claude with skills

/clear. Seriously.

Every request re-sends the full conversation history as input tokens. Once a task is done, that history is dead weight: old file reads, debugging logs, that long exchange where Claude went down the wrong path. You’re carrying a suitcase full of things you don’t need anymore.

/clear drops it.

/compact, but with instructions.

Just running /compact summarizes the conversation, but Claude decides what to keep. You can do better: /compact Focus on modified files and unresolved errors tells Claude exactly what matters. You can also make it permanent in CLAUDE.md so it applies every time Claude compacts automatically.

Dig deeper: Compact with a focus

In the main context, if you’re not careful.

Test runners, log processors, and doc fetchers can generate a lot of output. If that output lands in the main session, Claude re-sends it on every subsequent turn. Subagents run in their own isolated context window. The parent session gets a summary, not the raw output.

In skills and agents, structure workflows to delegate verbose operations to subagents. The main agent stays lean. In interactive sessions, Claude will usually make that call on its own, but you can always ask explicitly.

Dig deeper: Isolate high-volume operations

Pre-written scripts and hooks let you preprocess data before Claude sees it. Feeding Claude a raw test report when all you needed was the failures means Claude processes a lot more than necessary.

A 2026 study filtered low-value output from agent trajectories and found 40-60% fewer input tokens and 21-36% lower costs, with no impact on task success. Scripts and hooks are a simpler way to act on the same idea. The pattern scales well for agent-heavy workflows, but for small tasks the overhead isn’t worth it.

Dig deeper: AgentDiet, FSE 2026

It should have.

Skip the plan and Claude might build the wrong thing entirely. You pay for the wrong implementation, then pay to fix it. Plan mode makes Claude explore and propose an approach before touching any code. You review it, adjust it, then let it implement.

In interactive sessions, press Shift+Tab before giving Claude a large or ambiguous task. In skills, bake it in: structure the definition to include an explicit planning step before execution.

Dig deeper: Plan mode

Surprise: it’s not free.

The 1M context window costs the same per token as the default. It just holds 5x more tokens, so sessions stay uncompacted much longer and every turn carries a heavier payload. Stick with 200K unless you actually need it.

Dig deeper: Extended context

You can’t improve what you can’t measure.

Run /usage in Claude Code to see token usage and cost for the current session. Watch those numbers across sessions as you apply these practices. The difference is visible.

Running the API or tracking team usage? The Claude Console breaks it down by model, date, and API key.

Dig deeper: Using the /usage command, Claude Console

Scored 15 or above? Genuinely impressive.

Below that? You’re one or two practices away from making a real difference. Start with model selection, and go from there.

Thanks for reading!

The loop has two phases:

Set the following variables under the env key in .claude/settings.json for team-wide use, or in .claude/settings.local.json to keep them local.

All skills and scripts described in this post and the previous one are available as a Claude Code plugin in the gwenneg/blog-ai-friction-loop repository.

Clone it and start Claude Code with the plugin from your target project:

Then run /setup-friction-capture, which handles the full installation:

The .claude/ directory mixes things that should be committed (hooks, scripts, skills, shared settings) with things that should never be (friction logs, local settings, worktrees, lock files). The allowlist pattern looks like this:

The PR includes a note for reviewers about what data is sent and how to opt out.

As AI agents take on more of the coding work, keeping context docs accurate becomes critical. Friction will always exist. The question is whether it gets captured and fixed, or silently repeated across sessions.

I’m deploying this across several repositories at Red Hat and collecting feedback. This is one approach to the problem, and I expect it to change as teams adapt it to their own workflows.

The capture is purely reactive right now: it catches what went wrong, not what could go wrong. A major refactor can silently invalidate parts of the guidelines, and the loop only notices once an agent stumbles. That’s a known gap and something I want to address.

I’m also working on the developer experience, exploring ways to further minimize the effort required from devs while keeping the docs updated automatically. That could eventually mean getting rid of the manual step entirely.

If you try this or build something different, I’d love to hear about it. What breaks, what works, and what the next step looks like for your team. Feel free to share in the comments.

The /init-context-docs skill assesses a repository’s readiness for AI-assisted development, then bootstraps a layered set of context files. While AGENTS.md and the guideline files work with any tool that supports the standard, the loading behaviors described here are specific to Claude Code:

The unconditional layer is the most expensive in terms of context window tokens: it’s loaded every session regardless of the task. Files loaded at Claude’s discretion are the cheapest, but come with no guarantee. Path-scoped rules sit in between: deterministic loading, but only for matching files.

Several studies point in the same direction: longer context alone hurts LLM performance, even when the content is relevant (Du et al., 2025). Models pay the most attention to the beginning and end of their input; everything in the middle gets less (Liu et al., 2024; Wu et al., 2025). Anthropic frames context as "a precious, finite resource". On the flip side, well-formed AGENTS.md files are associated with ~29% faster execution (Lulla et al., 2026). But more isn’t better: LLM-generated context files with unnecessary content actually reduce task success rates compared to no context at all (Gloaguen et al., 2026).

This is why every file in the system is capped (200 lines for guidelines and AGENTS.md, 100 for CLAUDE.md), the most critical rules go first, verification commands go last, and everything in between is kept ruthlessly short.

Every layer is a tradeoff between loading guarantee and token cost. The question for each file is: does the agent need this every session, only for certain files, or only sometimes?

The skill starts by scanning the repo against the five layers described above and presents a baseline status showing what already exists and what’s missing. It then matches the repo against a curated list of guideline domains (e.g., security, testing, database), drops any that aren’t relevant, identifies additional domains not on the list (e.g., GraphQL, machine learning), and lets you adjust the final selection.

Once the domains selection is final, the skill launches one generation agent per domain, each focused exclusively on its area. An agent that only needs to produce a testing guideline can dig deep into your test patterns, rather than spreading its attention across the entire project. The same pattern applies to AGENTS.md, CLAUDE.md, and README: each gets its own generation agent. If a file already exists, the generation agent reads the existing content first and incorporates it, updating with new findings while preserving what’s still accurate.

Each generation agent reads a quality checklist before writing anything. The checklists enforce constraints like the 200-line cap, the necessity test ("Would removing this cause an agent to make a mistake?"), a ban on absolute language without evidence, and the requirement that every file reference actually exists in the codebase. Generation and verification agents share the same checklists, so both are measured against the same standard.

A separate agent handles verification. The one that wrote the content is biased toward believing it’s correct: research shows that LLMs systematically favor their own output (Panickssery et al., 2024) and fail to correct their own errors while successfully correcting identical ones from external sources (Tsui, 2025). There’s a catch, though: both studies examine self-bias within a single model. The skill uses a different model for verification (Sonnet instead of Opus), but both belong to the same Claude family, so some bias may carry over. Still, a fresh agent with a clean context checks file references against the actual codebase, validates factual claims with WebSearch, looks for contradictions across files, and flags duplication across layers. It only corrects inaccuracies. It doesn’t add new content.

After all agents finish, an automated-checks.sh script validates the generated files (line counts, imports, docs index, secret detection) and re-runs until all checks pass.

The skill finally offers to create a pull request with all the changes, so the generated docs go through the team’s normal review process.

Want to see how this works on your own project? Clone the gwenneg/blog-ai-friction-loop repository, then start Claude Code with the plugin from your target project:

Then type /init-context-docs. The skill will walk you through each layer, ask what to include, and let you skip anything that doesn’t apply. Expect it to take anywhere from a few minutes to about half an hour depending on the size of your codebase.

In my own testing, the generated docs clearly improved how agents work with projects: fewer wrong assumptions, less time spent correcting output. I don’t have metrics to back that up yet. It’s based on what I observed across a handful of repositories.

But even after all of this, the output is imperfect. Guidelines can sound plausible while being wrong about specifics, and some conventions only reveal themselves when the agent actually tries to follow the docs.

These are friction events, moments where the docs failed the agent:

Each one is a signal that the docs have a gap, something a concrete rule or example could have prevented.

In a follow-up post, I introduce an experiment to capture these friction events automatically at the end of every session and turn them into targeted doc improvements.

If you try /init-context-docs on your own codebase, I’m curious what it gets right, what it misses, and what you end up changing. Feel free to share your experience in the comments.

Thanks to Jiří Bönsch for helping me test and improve the /init-context-docs skill.

Add an optional final step to your skills that asks Claude to look back at what just happened and suggest improvements. Not to the code it produced — to the skill definition, CLAUDE.md, or any other project documentation that would have made the execution smoother.

Think of it as a mini retrospective that runs every time, at near-zero cost.

Here’s what I append to my skills:

A few things worth noting:

In my experience, most executions produce no suggestion — which is the right outcome. But when it does flag something, it’s usually a missing convention in CLAUDE.md or a step in the skill that assumed context Claude didn’t have. Those are exactly the kind of issues you’d never bother tracking down yourself.

It won’t revolutionize your workflow, but it’s a small investment that compounds over time.

Remote pipelines from Tekton let you reference pipeline definitions stored in external Git repositories instead of defining them locally in each project. They make it easier to share and maintain pipelines across multiple repositories.

Konflux is built on top of Tekton. Let’s see how we can leverage remote pipelines in a Konflux build pipeline!

Nothing shows it better than a good PR: gwenneg/blog-remote-konflux-pipeline#2. If you don’t have time to review the whole thing, here’s the TL;DR:

If the repository that hosts the remote pipelines publishes releases on GitHub, your repository can depend on a specific release instead of always using the latest version.

With this approach:

MintMaker works out of the box in repositories onboarded to Konflux and doesn’t require any additional configuration files. However, it is possible to customize MintMaker’s settings by adding a renovate.json file at the root of your repository. The default configuration is detailed in the Konflux doc.

If you plan on creating a repository to host remote pipelines, there are two things you’ll need to do:

Special thanks to Jiri Popelka for suggesting the Pipelines as Code annotation as an alternative to the Tekton Git resolver.

Imagine a centralized meteorological system that collects daily weather reports from 100 weather stations. Each station produces 10,000 reports every day, which are stored in the database and automatically deleted after 30 days.

Here’s what the SQL schema looks like:

The system depends on two essential SQL queries that require optimal performance:

Now, let’s see how we can make these queries faster!

You’re not just reading another post about PostgreSQL query performance. This post comes with a repository I created and used to test all the content discussed below: gwenneg/blog-postgres-execution-time. Hopefully, this repository will make it easier for you to experiment with different optimizations, possibly using your own schema and generated data.

If you’re not interested in testing optimizations, feel free to skip this section and jump to the next one. Otherwise, I’ll show you how to use my repository to run your own tests.

Clone the gwenneg/blog-postgres-execution-time repository. Open a terminal in either the single-table folder (no partitions) or the partitioned-table folder (with partitions) from the repository, depending on which approach you want to test. Then, start a container with:

The database initialization is complete when the following message appears:

You can now connect to the database.

Congrats! You’re now ready to run the SQL scripts provided in the repository or any other SQL queries:

These are the SQL scripts included in the repository:

When you run a SQL query in PostgreSQL, it isn’t executed immediately. First, the query planner analyzes the query structure, table sizes, indexes, joins, filtering conditions and available statistics to generate multiple execution plans. Then, PostgreSQL selects the most efficient plan and executes the query.

The EXPLAIN command displays the execution plan for a given query, providing details on execution time, row counts, indexes usage and more. That command is crucial for identifying slow queries, missing indexes, inefficient joins or outdated statistics. We’ll rely on it heavily throughout this post.

Reading an execution plan used to require highly specialized knowledge before the rise of Large Language Models. Today, if you submit your execution plan to an LLM, it can help identify weaknesses and suggest fixes. However, as with any LLM, be cautious of hallucinations and always double-check its recommendations.

Besides LLMs, tools like explain.dalibo.com can also help you visualize and understand your execution plan:

Let’s see what the execution plans for our two essential queries look like without indexes (except for primary keys) and using the default PostgreSQL settings.

More than 2 seconds to run each query - that doesn’t look good, right? But it’s no surprise since the weather_report table contains 30 million records and we’re filtering on unindexed columns.

Our queries both include a condition on the received_at and weather_station_id columns from the weather_report table, which contains 30 million records. Indexing these columns should help speed up the queries.

Run this query to check how much disk space your indexes are using:

Covering B-Tree indexes can be quite expensive and sometimes use nearly as much disk space as the table itself. On the other hand, BRIN indexes use a very small amount of disk space.

Indexes also slow down INSERT, UPDATE and DELETE queries. Every time a row is modified, PostgreSQL must update the corresponding index entries. This overhead on write operations is especially noticeable with high insert-rate workloads.

Indexes can really boost performance, but they can’t automagically fix a poorly written query.

In the current "fetch" query, PostgreSQL retrieves 89,992 rows and then filters out 89,092 of them. That doesn’t look right. Let’s see what happens if we replace the join with a subquery:

Wow, that’s an incredible improvement! The query that originally took 2069 ms without an index now runs in under 1 ms. How is that even possible?

The subquery helped move filtering before scanning. Because of that, PostgreSQL no longer has to fetch 89,992 rows and perform a materialized lookup for each one. That was a lot of unnecessary work. It’s gone now.

What about the "count" query? Could a subquery help reduce its execution time as well?

It’s not as impressive as the "fetch" query, but the subquery still significantly improves performance by allowing parallel scans and aggregation.

Covering B-Tree indexes can greatly improve query performance, but they have a weakness you should be aware of: heap fetches. A covering index allows a query to retrieve data entirely from the index without accessing the main table (heap), which would otherwise be expensive. However, this only works efficiently if the visibility map marks all necessary heap pages as "all-visible". If tuples are updated or deleted from a page and vacuum has not run, that page gets marked as "dirty" in the visibility map and PostgreSQL is forced to fetch rows from the heap, slowing down the query.

By default, PostgreSQL analyzes tables using the default_statistics_target setting, which defaults to 100. You can change this value globally or tweak it for specific columns if needed. Before you do, keep in mind that ANALYZE samples approximately 300 x statistics_target rows. With the default configuration, PostgreSQL samples around 30,000 rows.

Here’s how statistics can be changed for a specific column:

Increasing statistics on a column can help the query planner generate better execution plans and speed up queries, but it will also make ANALYZE slower. Consider it when:

The work memory can be increased at different levels:

If you see external merge or disk batches in an execution plan, it means PostgreSQL had to rely on disk instead of keeping operations in memory. That’s how you know the work memory could be increased.

There are other ways to optimize PostgreSQL query performance. Partial indexes and tuning WAL settings, for example, can be powerful tools depending on your workload. But this post should already give you a solid foundation with some of the most impactful techniques.

Thanks for reading! Hopefully, you’ve learned a thing or two that you can apply in your own environment to make your queries faster. If you’ve got tips or experiences to share, I’d love to hear them!

Happy optimizing!