Introduction: The Latency Challenge

In distributed systems, p99 latency often emerges as the silent killer of performance, despite healthy p50 and p95 metrics. This phenomenon is particularly acute in Go services, where the request lifecycle—from client initiation to load balancer routing and service processing—can be disrupted by straggler requests. These stragglers, consuming disproportionate resources, act as systemic bottlenecks, delaying subsequent requests and cascading into degraded user experience. The mechanical process here is straightforward: a single slow request, often due to resource contention or downstream dependency issues, holds up the goroutine scheduler, causing a backlog that amplifies tail latency.

Retries, a common mitigation strategy, proved ineffective—and in some cases, counterproductive. The causal chain is clear: retries increase load on already stressed resources, triggering retry storms that exacerbate latency. This is particularly evident in Go’s runtime, where garbage collection pauses and network variability compound the issue. The failure mechanism here is twofold: first, retries assume the problem is transient, but stragglers are often persistent; second, they lack awareness of system load, blindly adding pressure without resolving the root cause.

The breakthrough came from reframing the problem: stragglers, not failures, were the enemy. Hedged requests—sending a backup request after a timeout—emerged as a solution. The key challenge was determining the optimal hedging timeout without overloading the system. This decision point is critical: too short, and you waste resources on redundant requests; too long, and you miss the window to mitigate the straggler. The optimal timeout depends on queueing theory principles, balancing service time and request distribution to minimize tail latency without triggering resource exhaustion.

In practice, hedging reduced p99 latency by 74% in a real-world Go service, with minimal impact on p50 and a slight, expected increase in load. The implementation, packaged as hedge, demonstrates the effectiveness of this approach. However, hedging is not a silver bullet. It fails when downstream dependencies are the bottleneck, as parallel requests can saturate shared resources. The rule for choosing hedging is clear: if stragglers dominate tail latency and retries worsen load, use hedging with a timeout tuned to your request distribution. Missteps include over-triggering hedges, leading to unintended load spikes, and ignoring root causes like inefficient code or misconfigured load balancers.

Understanding the physical mechanics of latency—how requests queue, resources contend, and timeouts trigger—is essential. Without this, solutions remain superficial, addressing symptoms rather than causes. The stakes are high: unchecked p99 latency leads to system instability, operational inefficiencies, and user abandonment. As systems grow more complex, hedging stragglers offers a practical, measurable path to resilience—but only when applied with precision and awareness of the underlying mechanisms.

Diagnosing the Root Cause

Identifying the source of high p99 latency in our Go service required a systematic approach, combining trace analysis, statistical correlation, and controlled experimentation. The investigation revealed surprising insights into how straggler requests—not failures—were the primary culprits, despite initial assumptions.

Step 1: Isolating the Straggler Phenomenon

Using distributed tracing, we instrumented requests to map their lifecycle from client to response. The data showed that while p50 and p95 latencies were stable, p99 requests exhibited erratic behavior, often exceeding thresholds by orders of magnitude. These stragglers were not isolated incidents but systemic bottlenecks, consuming disproportionate CPU and memory resources due to Go’s goroutine scheduler being held up by slow requests.

Key observation: Retries exacerbated the issue, increasing load without resolving the root cause. This was confirmed by load testing, where retry storms triggered garbage collection pauses, further amplifying tail latency.

Step 2: Correlating Latency with Resource Contention

We employed statistical analysis to correlate latency spikes with resource utilization metrics. The results were striking: stragglers coincided with CPU saturation and network congestion, particularly in downstream dependencies. However, the surprising finding was that these issues were not due to failures but to persistent slow requests—a form of resource contention masked as transient errors.

Mechanism: Slow requests forced subsequent requests into a queueing backlog, where they waited for resources, creating a cascading delay effect. This was exacerbated by Go’s runtime characteristics, where goroutines blocked on I/O or synchronization primitives, stalling the scheduler.

Step 3: Testing Hedging vs. Retries

To address stragglers, we compared two strategies: retries and hedged requests. Retries, while intuitive, failed due to their blind addition of load without system load awareness. Hedging, however, reframed the problem by parallelizing backup requests after a timeout, effectively bypassing stragglers.

Experiment setup: We implemented hedging with a timeout threshold determined by queueing theory, balancing service time and request distribution. The results were dramatic—a 74% reduction in p99 latency with minimal impact on p50 and a slight, expected increase in load.

Edge case: Hedging failed when downstream dependencies were the bottleneck, as parallel requests saturated shared resources. This highlighted the importance of system load awareness in hedging timing.

Step 4: Validating the Solution with Chaos Engineering

To ensure robustness, we injected controlled stragglers using chaos engineering. The hedging strategy consistently outperformed retries, maintaining system stability under stress. However, we identified a critical failure mode: over-triggering hedges due to misconfigured timeouts, leading to unintended load spikes.

Rule for hedging: If stragglers dominate tail latency and retries worsen load, use hedging with a timeout tuned to request distribution. Avoid over-triggering by monitoring resource utilization and request queue lengths.

Surprising Findings and Practical Insights

• Stragglers, not failures, are the primary drivers of tail latency. Retries are ineffective or counterproductive in these cases.
• Hedging is a nuanced solution, requiring precise timeout thresholds and awareness of downstream dependencies.
• Understanding the physical mechanics of latency—queuing, resource contention, and timeout triggers—is essential for effective solutions.

By addressing stragglers through hedged requests, we not only reduced p99 latency but also gained deeper insights into the systemic issues underlying tail latency in distributed systems.

Key Insights and Surprising Discoveries

The journey to reducing p99 latency by 74% in a Go service revealed several counterintuitive insights that challenged conventional wisdom. Here’s what stood out—and why it matters.

1. Stragglers, Not Failures, Drive Tail Latency

The most surprising discovery was that straggler requests, not transient failures, were the primary cause of high p99 latency. While retries are commonly used to handle failures, they exacerbated the problem by increasing load without addressing the root cause. Stragglers—requests that consume disproportionate resources due to resource contention or downstream dependency issues—create a queueing backlog. This backlog cascades delays, as Go’s goroutine scheduler becomes blocked by slow requests, stalling subsequent processing.

Mechanism: Slow requests hold onto CPU and memory, preventing the scheduler from efficiently allocating resources to other goroutines. This contention amplifies tail latency, as the system struggles to recover from the backlog.

2. Hedging Outperforms Retries by Reframing the Problem

The effectiveness of hedged requests was unexpected. By sending a backup request after a timeout, hedging addresses stragglers directly, rather than blindly retrying. This approach reduced p99 latency by 74% while leaving p50 mostly unchanged. The key was tuning the hedging timeout using queueing theory to balance service time and request distribution.

Mechanism: Hedging parallelizes the handling of slow requests, reducing the time spent waiting for stragglers. However, it fails when downstream dependencies are the bottleneck, as parallel requests saturate shared resources, leading to resource exhaustion.

3. Retries Are a Blunt Tool—and Often Counterproductive

Retries, while intuitive, were found to be ineffective or harmful. They assume transient issues but lack awareness of system load, often triggering retry storms that worsen latency. In Go, retries also coincide with garbage collection pauses, further degrading performance.

Mechanism: Retries add load without resolving the underlying straggler issue, leading to a feedback loop where increased load slows down the system further. This is particularly problematic in Go due to its runtime characteristics.

4. Optimal Hedging Timeout Is Critical—and Fragile

The success of hedging hinges on the timeout threshold. Too short, and it triggers unnecessary backup requests; too long, and it fails to mitigate stragglers. The optimal timeout depends on the request distribution and service time, requiring careful tuning.

Mechanism: The timeout must account for the point at which a request is likely to become a straggler. This is determined by analyzing the latency distribution and identifying the inflection point where requests deviate from typical performance.

5. Monitoring Resource Utilization Is Non-Negotiable

Hedging introduces a slight increase in load, which is expected. However, without monitoring CPU saturation, memory usage, and queue lengths, hedging can lead to unintended load spikes. This is especially risky in production, where resource limits are stricter.

Mechanism: Over-triggering hedges saturates resources, negating the benefits of reduced tail latency. Monitoring ensures that hedging remains within safe bounds, avoiding resource exhaustion.

Rule for Hedging: When to Use It—and When to Avoid

Use hedging if:

• Stragglers dominate tail latency, and retries worsen load.
• The hedging timeout is tuned to the request distribution.
• Resource utilization is monitored to avoid over-triggering.

Avoid hedging if:

• Downstream dependencies are the bottleneck, as parallel requests will saturate shared resources.
• Root causes like inefficient code or misconfigured load balancers are unresolved.

Hedging is not a silver bullet but a precise tool for addressing stragglers. Its effectiveness depends on understanding the physical mechanics of latency—queuing, resource contention, and timeout triggers. When applied correctly, it transforms tail latency from a systemic issue into a manageable problem.

Implementation and Results

Addressing the high p99 latency in our Go-based service required a shift from traditional retry mechanisms to a more nuanced approach: hedged requests. The core issue wasn’t transient failures but straggler requests—slow responses that disproportionately consumed resources, blocking the goroutine scheduler and creating a queueing backlog. Retries, while intuitive, exacerbated the problem by increasing load and triggering garbage collection pauses in Go’s runtime, leading to a feedback loop of slower performance.

Hedging Strategy: Parallelizing Stragglers

We implemented hedged requests by sending a backup request if the primary request exceeded a calculated timeout. This timeout was determined using queueing theory, balancing the service time distribution and request latency inflection points. The mechanism works as follows:

• Trigger Condition: A backup request is initiated when the primary request’s latency exceeds the calculated timeout, identified via latency distribution analysis.
• Resource Impact: Parallel requests increase CPU and network load slightly, but this is offset by the reduction in tail latency. Monitoring resource utilization (CPU saturation, memory usage, and queue lengths) ensured hedging remained within safe bounds.
• Outcome: This approach reduced p99 latency by 74%, with p50 remaining largely unchanged. The slight increase in load was expected and manageable, as hedging targeted only stragglers, not all requests.

Comparing Hedging vs. Retries: A Causal Analysis

Retries and hedging address different root causes. Retries assume transient failures, blindly adding load without resolving stragglers. Hedging, however, parallelizes handling of slow requests, reducing wait time for stragglers. The effectiveness of each depends on the system’s failure mode:

• Retries: Optimal for transient network issues or intermittent failures. However, in our case, retries worsened latency by triggering retry storms and coinciding with garbage collection pauses.
• Hedging: Optimal when stragglers dominate tail latency. It fails when downstream dependencies are the bottleneck, as parallel requests saturate shared resources.

Rule for Hedging: Use hedging if stragglers dominate tail latency and retries worsen load. Tune timeout to request distribution and monitor resource utilization to avoid over-triggering.

Edge Cases and Limitations

Hedging is not a silver bullet. It fails in scenarios where:

• Downstream Bottlenecks: Parallel requests saturate shared resources (e.g., a database), negating latency benefits.
• Misconfigured Timeouts: Over-triggering hedges due to poorly tuned timeouts causes unintended load spikes, amplifying resource exhaustion.

To mitigate these risks, we validated the hedging strategy through chaos engineering, injecting controlled stragglers to test system resilience. This revealed that hedging outperformed retries under stress but required precise timeout tuning and resource monitoring.

Practical Implementation and Broader Impact

The hedging mechanism was packaged into a reusable library, hedge, with minimal integration required:

client := &http.Client{ Transport: hedge.New(http.DefaultTransport),}resp, err := client.Get("https://api.example.com/data")

The broader impact of this change extended beyond latency reduction. By addressing stragglers, we improved system stability, reduced operational costs associated with inefficiencies, and enhanced user experience. Unchecked p99 latency had previously led to cascading delays, causing system instability and user abandonment. With hedging, the system became more resilient to tail latency spikes, maintaining competitive performance even under load.

Key Takeaways

• Stragglers Drive Tail Latency: Focus on slow requests, not failures, to reduce p99 latency.
• Hedging Requires Precision: Tune timeouts using queueing theory and monitor resource utilization to avoid over-triggering.
• Retries Are Counterproductive: Address root causes (e.g., stragglers) instead of blindly adding load.

By understanding the physical mechanics of latency—request queuing, resource contention, and timeout triggers—we transformed a systemic issue into a measurable improvement, setting a new standard for performance optimization in distributed systems.

Lessons Learned and Best Practices

After dissecting the mechanics of high p99 latency in Go services, several actionable lessons emerged. These aren’t generic tips—they’re grounded in the physical and mechanical processes of request handling, resource contention, and system behavior under stress.

1. Stragglers, Not Failures, Drive Tail Latency

The root cause of high p99 latency in our case was straggler requests, not transient failures. Stragglers consume disproportionate resources (CPU, memory) due to Go’s goroutine scheduler being blocked by slow I/O or synchronization operations. This creates a queueing backlog, delaying subsequent requests. Rule: If p99 latency spikes while p50 remains stable, investigate stragglers before blaming failures.

2. Retries Worsen Latency by Amplifying Load

Retries are a blunt tool. In our case, they triggered retry storms, coinciding with garbage collection pauses in Go’s runtime. This created a feedback loop: more retries → more load → slower GC → higher latency. Rule: Avoid retries if stragglers dominate tail latency. Instead, address the root cause of slowness.

3. Hedging Outperforms Retries—But Only with Precision

Hedged requests reduced p99 latency by 74% by parallelizing backup requests after a calculated timeout. The key is tuning the timeout using queueing theory, balancing service time and request distribution. Rule: Use hedging if stragglers dominate and retries worsen load. Timeout must be precise; over-triggering hedges causes unintended load spikes. Edge Case: Hedging fails when downstream dependencies are the bottleneck, as parallel requests saturate shared resources.

4. Monitor Resource Utilization to Avoid Over-Triggering

Hedging increases load slightly, but without monitoring, it risks resource exhaustion. Over-triggering hedges saturates CPU, memory, or network, negating latency benefits. Rule: Monitor CPU saturation, memory usage, and queue lengths to keep hedging within safe bounds.

5. Understand the Physical Mechanics of Latency

Latency isn’t abstract—it’s a result of request queuing, resource contention, and timeout triggers. For example, Go’s goroutine scheduler stalls when slow requests block I/O, amplifying tail latency. Rule: Analyze latency distribution and correlate spikes with resource metrics to identify root causes.

6. Validate Solutions with Chaos Engineering

We validated hedging by injecting controlled stragglers and comparing it to retries under stress. Hedging outperformed retries but required precise timeout tuning and resource monitoring. Rule: Test solutions in realistic stress scenarios to uncover edge cases and limitations.

Practical Implementation

To apply these lessons, use the hedge library (available at https://github.com/bhope/hedge):

• Minimal Integration: Wrap your HTTP client with hedging transport.
• Timeout Tuning: Analyze latency distribution to identify straggler inflection points.
• Monitoring: Track CPU, memory, and queue lengths to avoid over-triggering.

When Hedging Fails

Hedging isn’t a silver bullet. It fails when:

• Downstream dependencies are the bottleneck: Parallel requests saturate shared resources.
• Timeouts are misconfigured: Over-triggering hedges causes load spikes.
• Root causes are ignored: Inefficient code or misconfigured load balancers persist.

Final Rule of Thumb

If stragglers dominate tail latency and retries worsen load → use hedging with precise timeout tuning and resource monitoring. Otherwise, address root causes like inefficient code or downstream bottlenecks.

Unchecked p99 latency leads to system instability, operational inefficiencies, and user abandonment. By understanding the mechanics and applying these lessons, you can transform latency issues into measurable performance optimizations.

Conclusion: The Path Forward

Digging into the root cause of high p99 latency in Go services revealed a surprising truth: stragglers, not failures, are the primary culprits. Traditional retries, often the go-to solution, exacerbated the problem by triggering retry storms and coinciding with garbage collection pauses, creating a feedback loop of increased load and slower performance. This is because retries add more requests to an already overloaded system, further blocking Go’s goroutine scheduler and amplifying tail latency.

The hedging strategy emerged as a superior alternative, reducing p99 latency by 74% in our case study. By parallelizing backup requests after a calculated timeout, hedging effectively short-circuits stragglers before they cascade into system-wide delays. However, its success hinges on precise timeout tuning—a misstep here can lead to over-triggering, saturating resources and negating latency gains. This is where queueing theory becomes indispensable, helping to identify the inflection point where a request transitions from “slow” to “straggler.”

Yet, hedging isn’t a silver bullet. It fails when downstream dependencies are the bottleneck, as parallel requests can saturate shared resources like databases. In such cases, addressing the root cause—whether inefficient code, misconfigured load balancers, or downstream bottlenecks—is paramount. Resource monitoring is equally critical; without tracking CPU saturation, memory usage, and queue lengths, hedging risks becoming a liability rather than a solution.

The key takeaway? Tail latency is a symptom of systemic issues, not isolated failures. Resolving it requires a curious, systematic mindset—one that combines trace analysis to pinpoint bottlenecks, chaos engineering to validate solutions under stress, and statistical analysis to correlate latency spikes with resource utilization. By approaching performance challenges with this rigor, we can transform latency issues into measurable optimizations, ensuring systems remain stable, efficient, and responsive even under load.

Rule for Hedging: Use hedging if stragglers dominate tail latency and retries worsen load. Tune timeout to request distribution, monitor resource utilization, and avoid if downstream dependencies are the bottleneck.

The path forward is clear: deep investigation pays off. By understanding the mechanics of latency, we can craft solutions that not only address symptoms but also fortify the system against future challenges. The potential for improvement is vast—and it starts with asking the right questions.

This is a submission for the Notion MCP Challenge

What I Built

I maintain a few open source projects solo, and honestly, the hardest part isn’t writing code — it’s everything around it. Triaging issues, figuring out which ones are bugs vs feature requests, reading through the codebase to understand what’s broken, and then actually getting around to fixing it. Most issues sit there for weeks.

Ghost Maintainer is my attempt to fix that. It’s an AI-powered system that turns Notion into an operations center for your GitHub repository. When someone files an issue, it automatically:

1. Lands in a Triage Queue in Notion
2. Gets classified by Gemini as a bug or feature request (with confidence scoring)
3. Routes to the right backlog — Maintenance Backlog for bugs, Feature Backlog for feature requests
4. If it’s a bug (and you have auto-fix on), it reads your entire codebase, proposes a fix, and opens a PR

The only thing left for you is reviewing the PR and hitting merge.

For bug reports, if you have disabled auto PR creation, then you trigger a fix using:

ghost_maintainer fix 3

For features, you trigger implementation when you’re ready:

ghost_maintainer implement 9

That kicks off the same pipeline — reads the codebase, writes the code, opens a PR.

The whole thing installs with one command from inside your repo:

curl -sL https://raw.githubusercontent.com/sbis04/ghost_maintainer/main/install.sh 
  -o install.sh && 
  bash install.sh && 
  rm install.sh

It asks for your Notion, GitHub, and Gemini tokens, then sets up everything — databases, secrets, workflows, the lot.

I also built a full MCP server (in Dart, using the dart_mcp package) that exposes 5 tools, 2 resources, and 2 prompts. You can connect it to Gemini CLI or Claude and interact with your maintenance backlog conversationally — triage issues, investigate bugs, deploy fixes, all through natural language.

The Notion workspace

• Triage Queue — every issue starts here, AI sorts it
• Maintenance Backlog — confirmed bugs with AI summaries, priority, and PR links
• Feature Backlog — feature requests waiting for implementation
• Archive — completed items with resolved dates
• Project Vision Statement — you edit this to guide how the AI thinks about your project

Video Demo

Link to Code on GitHub

The project has three main pieces:

• ghost_maintainer_mcp/ — The MCP server (Dart). 5 tools, 2 resources, 2 prompts.
• notion_setup/ — The CLI tool and GitHub Action scripts that power the automation.
• .github/workflows/ — 4 workflows: issue ingestion, triage, implementation, and PR archival.

The CLI doubles as a globally installable tool (dart pub global activate from the repo, no publishing needed).

How I Used Notion MCP

Notion is the central nervous system of Ghost Maintainer. Every piece of data flows through it.

As the Issue Tracker:
The Triage Queue, Maintenance Backlog, Feature Backlog, and Archive are all Notion databases. Each has structured properties (Stage, Priority, Labels, AI Summary, PR URL, Issue Number) that the automation reads and writes. When AI triages an issue, it updates the Notion page with its analysis. When a PR is created, the URL gets linked back. When the PR merges, the item moves to Archive with a timestamp.

As the AI’s Memory:
The Project Vision Statement page is a Notion document that the AI reads before every triage and investigation. It contains your project’s mission, principles, and current focus areas. This means the AI doesn’t just categorize issues mechanically — it understands that “security issues are always P0” or “we’re in a stability phase, deprioritize new features.” You edit a Notion page, and the AI’s behavior changes.

Through MCP:
The MCP server exposes Notion data as resources (ghost://vision for the vision statement, ghost://backlog/summary for live stats) and provides tools that read from and write to Notion. When you ask the MCP server to triage an issue, it pulls the vision from Notion, calls Gemini, then writes the results back to Notion. The protocol bridges conversational AI with structured project data.

The flow end to end:

GitHub Issue
    --> GitHub Action
    --> Notion Triage Queue
    --> AI Classification
    --> Notion Backlog
    --> AI Investigation
    --> GitHub PR
    --> Merge
    --> Notion Archive

Every step is visible in Notion. You always know where every issue is, what the AI decided, and why. No black boxes.

What I like most about this setup is that Notion becomes the source of truth that both humans and AI operate on. I check my Notion dashboard, I see what’s happening. The AI checks the same dashboard. We’re looking at the same board.

Terms like “per-process controls” are understated in the programming world, and “quantized execution” is the key that makes these terms make sense.

I made a threading architecture that embodies “quantized execution” and “per-process controls” and learned that the key to a productive codebase is having a “surface of execution” that speaks for itself. Each operation is quantized to a unit of arguments (token) and each unit represents a flowing surface of metadata and heuristics.

The architecture I made TokenGate is described best as “an async threading hybrid model with per-process controls”.

In TokenGate there’s two layers of task authority, the first layer is the CPU and IO process tags to control affinity, the second is a direct admin control panel operated on the localhost of the rig running TokenGate.

Example of the control mechanisms in the GUI

Having (per-task or) per-operation commands to change the runtime is helpful, undoubtedly. What I want to discuss is if people would get on board with this if it was simple and practical?

This could be done in a variety of ways and is a huge enhancement to any code base.

As an example; if you had an analysis algorithm for tasks and a flag system, then you could act on this.

In whatever way (there’s plenty) a codebase could add controls to 100% of their systems critical operations. They could monitor their successful returns, predict memory needs, stop processes which are failing, and retain “control” by having a functional “surface of truth”.

This is possible when you “quantize an execution” or when functions are wrapped and decorated as tokens or if you go savvy with some other dynamic means of analysis and task manipulation. Point is, a “unit of execution” that has a “surface of truth” is much more “programmable” than a series of locked and time dependent operations using generic returns/state.

This doesn’t mean all functions are meant to have “controls” but anything which alters or returns data in this perspective should.

Am I the only one who thinks “task controls and analysis” is something that should be more of a conversation?

On a deeper level is “process analysis/mapping” and “ML integrated process handling” topics anyone else is intrigued by?

Also who would be on board with a new paradigm of task execution and analysis like this?

I’ve been building products with Claude Code for months. Every time I asked “is this implementation correct?”, the answer was “yes, it’s properly implemented.” Every time. Even when the code had bugs that broke in production.

Then Anthropic published a blog post that explained exactly why. I mapped my setup against their findings, and realized: my evaluator layer was almost empty.

Here’s how I rebuilt it.

Jump to:

• What Anthropic’s experiment showed
• Mapping this to Claude Code
• Layer 1: Rules — always-on review criteria
• Layer 2: Skills — on-demand reviewers
• Layer 3: Agent separation — who builds vs who reviews
• 3 principles for evaluation design
• Final file structure
• Harness design checklist

What Anthropic’s experiment showed

In March 2026, Anthropic published “Harness design for long-running apps” — experiments where AI agents autonomously built apps over multi-hour sessions.

The headline finding:

Agents asked to evaluate their own work tend to confidently praise it, even when it’s clearly mediocre to human observers.

It gets worse. Agents would spot real problems, then wave them off as unimportant and approve anyway. They’d skim instead of testing edge cases. Anthropic themselves put it bluntly: “Claude is an inadequate QA agent out of the box.”

Their fix was splitting generation from evaluation — three agents:

The difference was stark:

The evaluator checked 27 criteria per sprint and filed bug reports like “fillRectangle exists but doesn’t fire on mouseUp.”

Reading this, it clicked: Claude Code’s config system can give you the same split.

Mapping to Claude Code

Here’s the mapping:

When I laid out my own setup this way, the gap was obvious. CLAUDE.md had project context. Skills had coding patterns. But nothing was actually checking whether the output was correct. I was asking the generator to review its own work — the exact failure mode Anthropic documented.

Layer 1: Rules — always-on review criteria

Files in ~/.claude/rules/ load every session. Put things here that AI won’t do on its own but that matter in production.

Here’s a taste of my Supabase/PostgreSQL rules (30 total):

# ~/.claude/rules/supabase-postgres.md

## Index FK columns
PostgreSQL does NOT auto-index foreign key columns.

## RLS performance
Wrap auth.uid() in SELECT to prevent per-row execution:
- BAD: using (user_id = auth.uid())
- GOOD: using (user_id = (select auth.uid()))

## Cursor-based pagination
- BAD: OFFSET (slow on deep pages)
- GOOD: WHERE id > $last_id ORDER BY id LIMIT 20

Without this rule, the AI generates auth.uid() without the SELECT wrapper every time. Works fine with small tables. Tests pass. Then production slows to a crawl as rows grow. Classic “surface-level test that misses the deeper bug” — exactly what Anthropic described.

I think of rules as “never step on this mine again” files. Every rule started as a real mistake.

Layer 2: Skills — on-demand reviewers

Rules load every session, so too many will eat your context window. Anything task-specific goes into skills (.claude/skills/), which show only their titles by default and load on demand.

You can wire up keyword-triggered activation:

# ~/.claude/CLAUDE.md (excerpt)

## Automatic Skill Activation

### Testing / TDD
**Trigger:** test, TDD, coverage, unit test
**Action:** Run test-driven-development skill

### Bug / Error handling
**Trigger:** bug, error, debug, broken
**Action:** Run systematic-debugging skill

### Completion check
**Trigger:** done, verify, review, check
**Action:** Run verification-before-completion skill

The completion check is the big one. In Anthropic’s experiment, the evaluator ran checks at the end of each sprint. Same idea here — say “verify this” and a quality checklist kicks in behind the scenes.

I run 27 skills total. 7 auto-activate on keywords.

Layer 3: Agent separation — who builds vs who reviews

The core insight from Anthropic: separate the builder from the reviewer. In Claude Code, you do this through agent orchestration:

# ~/.claude/rules/agents.md

## Role: Manager
You are a manager and agent orchestrator.

**Rules:**
- Never implement directly — delegate all implementation to Sub Agents
- Break tasks into small units and run PDCA cycles

## Delegation
### Always delegate:
1. Code implementation
2. Debugging
3. Test creation

### Manager handles directly:
1. Task decomposition
2. Progress verification
3. Plan adjustment

The trick: pin the main Claude as “manager = reviewer” and push all implementation to Sub Agents. This gives Claude Code the same generator/evaluator split that Anthropic proved works.

Main Claude doesn’t write code. It reviews what Sub Agents produce. Planner + evaluator = main Claude. Generator = Sub Agents.

3 principles for evaluation design

1. Weight your criteria toward what AI misses

Anthropic’s frontend experiment used 4 criteria: design quality, originality, technical execution, functionality. They weighted design and originality higher — because the AI already did well on technical execution and functionality.

Lower the weight on things AI handles naturally. Raise it on things AI overlooks.

In practice:

• Low weight (AI’s fine): syntactically correct code, basic API endpoints
• High weight (AI misses): performance traps (auth.uid() without SELECT), UX decisions that affect conversion, security blind spots

2. Prune your harness as models improve

From Anthropic:

Every component of a harness encodes an assumption about what the model can’t do alone, and these assumptions can be wrong or quickly become outdated as models improve.

When they went from Opus 4.5 to 4.6, sprint decomposition became unnecessary — the newer model handled long sessions on its own. Same thing happens with your Claude Code rules. Something essential today may be dead weight next quarter.

I’ve revised my CLAUDE.md 8 times. The test for each line: “If I delete this, will the AI make mistakes?” No? Cut it.

3. Better models mean more harness possibilities, not fewer

The space of interesting harness combinations expands rather than contracts as models improve.

Sounds backwards, but it matches my experience. As the AI gets smarter, you can delegate more. But the remaining evaluation points get more nuanced, more subtle, and higher-stakes. The easy rules go away. The hard judgment calls stay.

Final file structure

~/.claude/
├── CLAUDE.md                # Planner layer (project overview + skill triggers)
├── rules/
│   ├── agents.md            # Generator/evaluator split
│   ├── supabase-postgres.md # Review criteria (DB/RLS, 30 rules)
│   ├── react-nextjs.md      # Review criteria (React/Next.js)
│   ├── security.md          # Review criteria (security)
│   ├── coding-style.md      # Code quality
│   └── testing.md           # Test quality
└── skills/                   # On-demand reviewers
    ├── verification-before-completion  # End-of-task checks
    ├── systematic-debugging            # Debug-time checks
    ├── test-driven-development         # TDD enforcement
    └── ... (27 total)

How it maps to Anthropic’s architecture:

• CLAUDE.md → Planner artifact (the product spec)
• rules/ → Review criteria (the sprint contract)
• skills/ → Specialist reviewers (activate when needed)
• agents.md → Builder/reviewer separation

Harness design checklist

Planner layer (CLAUDE.md)

• [ ] Project overview and constraints documented
• [ ] Design decisions and their rationale included
• [ ] Under 200 lines (bloated CLAUDE.md degrades instruction-following)

Review criteria (rules/)

• [ ] Cover what AI misses, not what it already does well
• [ ] Weighted toward production-critical concerns
• [ ] Regularly pruned as models improve

On-demand reviewers (skills/)

• [ ] Separated by domain (DB, React, security, etc.)
• [ ] Keyword auto-activation configured
• [ ] Completion verification skill exists

Builder/reviewer separation (agents.md)

• [ ] Main Claude delegates implementation to Sub Agents
• [ ] Verification flow for implementation results

Links

• Anthropic’s original post: Harness design for long-running apps
• Claude Code docs: docs.anthropic.com
• Japanese version (Zenn): https://zenn.dev/lova_man/articles/99777e473b3c2c

👋👋👋👋

Looking back on your week — what was something you’re proud of?

All wins count — big or small 🎉

Examples of ‘wins’ include:

• Getting a promotion!
• Starting a new project
• Fixing a tricky bug
• Taking a well deserved day off! 💤💤💤

Happy Friday!