Brandon Casci

The Gravity Between You and the 100X Dark Factory

2026-04-07T14:00:00+00:00

2026-04-07

The Gravity Between You and the 100X Dark Factory

I heard Nathan B Jones talking about the concept of a living resume and how he thought the current hiring model was toast. The idea stuck with me. I expanded it into a product called Profyle: a professional profile platform with three layers of depth. A scannable surface view, expandable stories behind each role, and an AI conversation layer where visitors can ask questions about your background. LinkedIn discovers you. Profyle helps people understand you.

I decided to use it as an experiment. Could I build it with full AI autonomy?

Dan Shapiro drew an analogy to self-driving car levels and came up with five levels of AI-assisted development. At Level 4, the human writes specs and crafts skills. The AI implements. At Level 5, you have a “Dark Factory”: specs go in, shipped software comes out, no human in the execution loop. The term comes from lights-out manufacturing. StrongDM shared a public example of this: three engineers, no human-written or human-reviewed code, external test scenarios as enforcement.

I aimed for Level 5. I landed at Level 4, with Level 5 moments on the mechanical parts. This is what the attempt looked like and where the boundary actually sits.

Before the Factory

Before any AI touched any code, I had to figure out what to build:

Product and market research (some automated with AI)
Product definition and intention statement
Architecture document
Broke it all down into implementable specs as GitHub issues

Those added up to the MVP.

The factory doesn’t know what to build. I did.

The Factory

I didn’t just build Profyle. I built a factory model using Claude Code’s capabilities (rules, skills, subagents, and hooks) to see how close to autonomous I could get. At Level 4 and above, building and tuning that system IS the job.

Rules (24 files) auto-load by file context and cover code style, architecture, testing standards, and operational guides. Failures during the project fine-tuned them, some led by me, some by agents recognizing issues and amending the rules themselves.

Skills (8 Profyle-specific) are pipelines for repeatable workflows. /profyle-ship goes from board issue to merged PR in one command: branch, TDD, review, PR, merge.

TDD actor separation means the agent that writes tests is never the agent that writes code. The tester doesn’t know the implementation. The coder doesn’t write the tests.

Convergence loops are resolution-based quality control. The loop continues until every finding is resolved, not after a fixed number of iterations. A circuit-breaker prevents infinite loops.

These patterns came from prior projects. New problems came up as they were adapted for longer-running autonomous sessions.

The Numbers

Metric	Value
Commits	514
Active development	~8 days
Rules files	24
Skills (total / Profyle-specific)	40 / 8
Test files	181
Test code	~24,000 lines
App code (Ruby)	~5,400 lines
Test-to-code ratio	4.4:1
ViewComponents	28
RubyLLM Agents	9
Models	19
Controllers	48

Testing coverage is high, but some of the early tests were duplicative or too verbose. Those were written before the TDD rules were optimized.

What Worked

Work was organized into milestones (M0: Skeleton through M6: Go Live). Each issue was scoped to be individually implementable from the spec alone. The agent can’t ask clarifying questions, so ambiguity meant expensive guesses. Only issues marked “Ready” could enter the pipeline.

The feedback loop was a big part of making this work: bad output got diagnosed, distilled into a rule, and didn’t repeat. A couple examples of what that looked like:

AI refused to use WebMock/VCR, stubbed API calls with invented payloads, tests passed with zero connection to reality. Fix: forced VCR for real response recording.
RubyLLM schema DSL missing object wrapper generated wrong JSON structure with no compile-time error. Fix: mandatory unit test on to_json_schema output for every schema.

What Didn’t Work

UX

Unlike backend code, where the AI arrived at quality solutions with the right rules and context, UI and UX were a different story. Same access to information, but the output quality didn’t follow.

A Claude Code skill called ui-ux-pro-max gave the AI a design intelligence framework for making better style and pattern decisions.

I also added simple_form and ViewComponent with DaisyUI helpers to narrow the decision space: card here, badge there, textarea instead of text input. Less guessing.

It all improved the output, but I still directed creative decisions throughout. Clearest Level 3 territory in the project.

Test Quality

The factory wrote a lot of tests, but early quality was uneven. System tests targeted isolated UI elements instead of complete user workflows. Edge cases were missing. Mocks and stubs were overused, obfuscating bugs in some cases.

I fixed this through interactive sessions where I diagnosed what was going wrong and tightened the testing rules over time. Later output was solid.

Review Skipping

The most expensive mistake in the project. The ship pipeline has a dedicated reviewer subagent, but the orchestrator would sometimes do its own review instead of spawning it. In one early session, it skipped the reviewer on 17 of 18 PRs. The sign-in button broke across three consecutive PRs because the reviewer never ran.

I tightened the rule language and added a prerequisite checkpoint: the orchestrator must verify that reviewer output exists before creating a PR. After tightening, reviews happened. But it’s all instruction-based. There are no hooks or system gates enforcing it. The AI reads the rule and chooses to comply.

That’s the limit. The AI supervises itself.

Where I Actually Landed

While the initial MVP fell short, it was a good foundation that needed additional attention. I spent a few days in QA and corrective cycles. Some ideas needed rethinking.

Here’s where each layer actually landed:

Area	Level	What that meant
Models, controllers, services, AI integration	L5	Spec in, merged PR out
Overall project (specs, rules, diagnostics)	L4	I drafted specs, diagnosed gaps, tuned rules
UX and product strategy	L3	Tight conversational iteration

Level 4 worked because of iterative rule-hardening: ship, find a gap, write a rule, ship better. The factory improved because the rules got more precise, not because the AI got smarter.

The gap to Level 5: the factory mostly can’t find its own problems, and the AI supervises itself through the process. The rules are the most transferable artifact. They encode hard-won decisions and carry forward to the next project.

The Path to Level 5

Tools like Claude Code, Gemini, Codex and others can’t do Level 5 yet. The AI supervises itself: you give it a skill with 10 steps and trust it to run them all, including reviewing its own work. Subagents and hooks only get you so far. The AI is still the orchestrator.

Level 5 needs an external runtime controlling the process while the AI handles focused tasks in separate sessions. This is why we’re seeing things like StrongDM’s approach and open source projects like Fabro coming about.

The external orchestrator handles the flow, and people with deep industry experience like Alex Bunardzic and Bryan Finster can now encode their methodologies into the AI’s configurations: TDD discipline, continuous delivery, fast feedback. If Alex wants a test mutation step in the pipeline, I believe he’d get it with this approach. I’m looking forward to trying it.

I knew what Level 5 was about through reading. Doing it showed me where the ceiling actually is. Who supervises the process, not how good the AI is at following instructions.

How I Came to Understand the 100x Claim

2026-02-24T20:17:00+00:00

2026-02-24

How I Came to Understand the 100x Claim

First people bragged about 3-5x productivity gains from AI, then 10x, and now 100x. Usually without much clarity beyond references to parallelism and orchestration. I’d read these claims and think, OK, but what does that actually look like? What are you doing differently that gets you there?

I was skeptical for a while. Then I lived through it, and I started to understand what these people are probably trying to describe. They’re mostly bad at explaining it, and I think that’s because the gains don’t come from any single technique. They come from building up an infrastructure over time that eventually changes what one person can operate.

This is how I got there.

Getting Incrementally Better

I didn’t start out great at employing AI for real work. The early months were a lot of trial and error, figuring out what Claude Code could actually handle versus what I still needed to do myself.

I got incrementally better. I wrote CLAUDE.md files with domain knowledge and coding standards, built custom skills for repeatable workflows, and learned how to spec work so agents could pick it up without a bunch of back-and-forth. I started building composable rule sets so conventions stayed consistent across projects.

As confidence grew, I got more ambitious. I joined other open-source projects. I added ancillary applications to the business. Each improvement compounded on the last: more context documented meant better agent output, which meant more confidence to delegate, which meant I could take on more scope.

Hitting the Bottleneck

The gains plateaued once I was running multiple projects at the same time. Boswell had two active codebases and production customers. Harmonic needed attention. I was maintaining a fork of the litestream-ruby gem. And I had this blog.

Switching tabs, switching console sessions, switching mental contexts. AI was helping inside each project, but I was still the bottleneck between them. Not only could I not take on much more, it was mentally taxing to juggle that many different codebases and topics at once. The gains from faster code generation had a ceiling because I could only context-switch so fast.

Exploring Orchestration Across Systems

I realized the bottleneck wasn’t the agents or the code. It was me directing everything manually. I needed to automate the delegation itself.

I built boswell-backoffice: a Fly.io VPS that runs the same Claude Code agents I use locally, triggered by GitHub events instead of me typing in a terminal. n8n listens for GitHub webhook events like issues being labeled or comments being posted. Dagu orchestrates the pipeline: post a start comment, set up the workspace, run Claude, commit the results, and post a completion comment.

Agents commit as “Boswell Agent” or “Claude Agent,” and it’s all visible in the git history. I started with a different orchestration tool (AI Maestro), replaced it with Dagu, and I’m still prototyping. The specific tools matter less than the pattern: I moved from directing agents manually to delegating through project management tools. GitHub Issues became work orders. GitHub Projects became the prioritization layer.

The issue workflow has two labels. agent-spec takes a casually written issue and explodes it into a full implementation specification. The agent reads the rough description, pulls in all the project context it has access to (CLAUDE.md files, conventions, domain knowledge), and rewrites the issue body with a detailed spec. My original draft gets preserved in a collapsed section at the bottom. Then agent-implement picks up that spec and does the actual work: write the code, run tests, commit, push, and open a PR. I can also drop an @agent comment on any issue or PR to give ad-hoc instructions.

This means I can write a few sentences about what I want while I’m thinking about it, label it agent-spec, and come back later to a full spec I can review and refine before kicking off implementation. The agent does the tedious part of translating intent into detailed requirements, using the same project knowledge I’ve been building up all along.

What agents have shipped through this pipeline

Some examples:

Issue #252: An agent investigated a SQLite transaction rollback bug across 7 commits, documented the full investigation, wrote regression tests, and opened PR #253 (240 additions, 13 deletions).
Issue #283: An agent implemented console subscription management for tenants, including a new controller, dialog UI, tests, and addressed PR review feedback.
Just about anything I feel like slinging through this instead of kicking off locally at the console.

The Litestream Incident

This is where it clicked for me.

Boswell’s production data volume hit 100% full. Litestream replication staging directories and WAL files were consuming about 906MB of a 974MB volume. The actual databases were around 2MB. I’d been seeing recurring SQLite errors across multiple issues, and the root cause turned out to be Litestream v0.3.13, which had known unbounded disk growth bugs that were fixed in v0.5.x. The upstream litestream-ruby gem was still bundling the old version, and the maintainer was unresponsive and not taking pull requests.

All of this happened on the same day (2026-02-22):

I wrote issue #276 with the full spec for what needed to happen.
One agent forked litestream-ruby, upgraded the binary from v0.3.13 to v0.5.8, added a litestream:download rake task, updated CI and docs, and bumped the version. It used proper PR workflow on the fork.
Another agent picked up the fork in boswell-app, updated the Gemfile, converted the config format, updated the runtime config service, fixed the Dockerfile through 4 iterative attempts, and got the full test suite passing.
I reviewed the work, merged, and deployed. Production issue resolved.

Two different codebases, two different problem domains (gem internals vs. Rails app deployment). Without the orchestration, I’d be manually reading gem source code, forking, upgrading, then context-switching to boswell-app to update config and debug Docker builds. It starts to hurt my head after a while.

With delegation, I wrote the spec, kicked it off, and reviewed the output. The agents handled the cross-codebase coordination and the iterative debugging themselves.

Agents Reviewing Each Other

I run two agents in a write/review loop. Both have access to the same conventions and standards through CLAUDE.md files, rules, and skills. They iterate until the work meets the standards. The responder has an out if the reviewer makes unreasonable calls, acting as a circuit breaker so they don’t loop forever.

The first result from a spec is generally good, but there’s usually some tech debt you don’t want to let accrue into something bigger. The review loop dials it in before I ever see it.

I’ve heard some claim this kind of song-and-dance routing is defensive and an indication of how weak the technology is. My opinion: so what, it works, it’s fast, and I’ve seen people on actual teams cause worse problems.

PR #253 shows the full loop. The investigation was documented, the fix was implemented, regression tests were written, and review feedback was addressed, all before I looked at it.

Trust and Staying in the Loop

Trust didn’t come automatically. I had to build it up over time by watching agents work and verifying results. Early on I reviewed everything closely, which was the right call. As the conventions matured and the review loops proved reliable, I gradually shifted to reviewing final output instead of watching every intermediate step.

I’m still the final arbiter on every merge. At my scale, that’s not a bother, so I’m not letting go of that yet. Besides, the review process surfaces opportunities to update agent knowledge. Sometimes I spot a convention gap or a better pattern that should be documented. That feedback loop improves future output, and agents also pick up on improvements implicitly as the codebase evolves.

I suspect a lot of people are in the early trust-building stage. The systems that make delegation work aren’t obvious until you’ve built them and lived with them for a while.

Coming to Understand the Claim

I don’t think it’s literally 100x. Not to me, anyway. But compared to a decade ago, even a year ago, what I’m able to do as one person is kind of astounding.

Some of the gains have nothing to do with typing speed. They show up in being able to:

Delegate across codebases I’d otherwise have to context-switch between manually
Run business operations through the same project management tools as code work
Let agents handle the iterative debugging and review cycles
Take on more projects and more scope without burning out

None of that shows up if you measure “time to write a function.” It shows up when you look at what one person can operate across a month.

What I Can Refine From Here

The orchestration layer is still a prototype, and I can see building a solid application around it. Queue concurrency is limited to 1 because of VPS constraints, but that’s fine at my scale. A ton more could get done with vertical upgrades alone.

There’s room to improve: smarter issue routing, more robust review loops.

The infrastructure for conventions and knowledge keeps paying dividends as it matures. Each project I add gets easier because the patterns are already documented and the agents already know how to follow them.

Where This Leaves Me

I came into this skeptical of the 100x claim. After building the infrastructure and living with it, I get what people are trying to say. They’re just not always articulating the details, and most don’t seem to mention the supporting systems you need to build before any of it works.

The gains are real, they’re compounding, and they’re operational. They’re not just about writing code faster. I’m one person running a multi-project business with production customers, and the path forward keeps getting clearer. Mature the orchestration from a string-together prototype into a solid app. Then move on to growth wheels, marketing automation, or really anything else I feel like doing.

Composable Rules: How Small Teams Match Big Company Output Without the Bloat

2025-12-25T01:16:00+00:00

2025-12-24

Composable Rules: How Small Teams Match Big Company Output Without the Bloat

Small teams and solo developers compete with funded companies every day. Traditionally, small teams defended niches by being nimble. Now they can simulate the parts of bigger institutions that work without the overhead.

Big companies have resources:

Multiple developers
QA teams
DevOps
Established processes

They also have bloat:

Coordination overhead
Committee decisions
Slow tool adoption
Competing coding styles

Small teams have agility:

Instant tool adoption
Quick pivots
Consistent vision

But without systematic infrastructure, agility can get tricky. Every new project starts over. Knowledge doesn’t compound.

How do you get big company output without the bloat?

Build reusable systems: - Conventions that travel - Workflows that adapt - Infrastructure that scales without headcount

This systematizes what big companies can’t: - Speed of adoption - Consistency of vision - Low coordination overhead

For me, this started with solving project memory - where you ingrain your intents, values, and processes into your AI helpers. While this article focuses on modular coding rules, the same process applies to business rules, customer feedback patterns, product decisions, and more. For software-centric businesses, coding conventions are the natural starting point.

I had already solved project memory. Reference files and domain-specific CLAUDE.md files throughout my codebase kept Claude Code consistent with my conventions.

When Claude shipped the rules feature for .claude/rules/, I blew it off. Why rush to adopt something when I’d already solved the problem?

But I finally tried it. What an improvement.

The rules feature is cleaner, more organized, and way easier to manage than scattered CLAUDE.md files. I was well on the way of centralizing this into a consolidated references directory, but the Claude rules feature is a better solution.

You drop markdown files in .claude/rules/, Claude loads them automatically. Better separation of concerns. Better composability.

Now I had a different problem: setting up those rules for every new project.

The Manual Setup Problem

You can’t just copy your entire .claude/rules/ folder from one Rails project to another. Each project uses different gems and libraries.

Project A uses Pundit for authorization and Postgres. Project B uses SQLite and no authorization gem. If you copy all your rules, Project B gets Pundit conventions it doesn’t need and Postgres patterns for a database it’s not using.

What I Built

I organized my battle-tested Rails conventions into composable rule sets. Run one command, it detects what your project actually uses, and copies only the relevant rules.

I’m calling it the Hustler marketplace. Lean plugins for small businesses and small teams. Easy, pragmatic, low complexity.

The first plugin is hustler-rails for Rails conventions.

Why “Hustler”

Small businesses and small teams need tools that just work. No complexity, no over-engineering, no corporate bloat.

Lean plugins. Pragmatic solutions. Low noise.

How Composable Rules Work

Rules use frontmatter to declare when they apply:

---
paths: app/policies/**/*.rb, app/controllers/**/*.rb
dependencies: [pundit]
---

# Pundit - Authorization

Always put authorization in policies, not controllers...[and details about coding them]

The paths field is Claude Code’s feature for conditional rule loading, it accepts comma-separated glob patterns. This example loads authorization rules when working on either controllers or policies, so Claude always has the full authorization context regardless of which file you’re editing.

The dependencies field is my own convention that helps the init command detect which rules to copy. The extra fields don’t conflict.

Universal rules have no dependencies and always get copied. Dependency-specific rules only get copied if your project uses that gem.

The plugin detects dependencies by common sources like:

Gemfile.lock for Ruby gems
config/database.yml for database adapter
package.json, importmap, CDN links for JS libraries

Run /hustler-rails:init and it composes the right rule set for your project.

Real Example

/hustler-rails:init

Output:

Detected dependencies:
  - pundit (authorization)
  - beercss (UI framework)
  - sqlite3 (database)

Copying rules:
  ✓ models/conventions.md
  ✓ controllers/conventions.md
  ✓ testing/conventions.md
  ✓ authorization/pundit-policies.md
  ✓ views/beercss-components.md
  ✓ database/sqlite-patterns.md

Skipped (not detected):
  - devise (not in Gemfile.lock)
  - postgresql (using sqlite3)

📦 41 rule files copied to .claude/rules/hustler-rails/

Some of these dependencies are my personal favorites for non-corporate projects, but it’s no big deal to add support for other configurations

You get conventions for what you’re actually using. Nothing more.

Why Copy Instead of Reference?

The plugin copies rules into your project rather than keeping them in the plugin and referencing them. This lets you tweak rules per project without forking the whole plugin.

Maybe you mostly follow my testing conventions, but your project has one special case. Edit .claude/rules/hustler-rails/testing/conventions.md and adjust it. Your change only affects this project.

Future idea: an override system where rules stay in the plugin and per-project adjustments live separately. Haven’t built that yet.

What’s Included

Thin model patterns
Command pattern for business logic
RESTful controller patterns
Test structure and anti-patterns
Authorization with Pundit
Component patterns for BeerCSS and Turbo
SQLite-specific patterns (multi-db, FTS5 search)
Query optimization patterns

Organized by domain: models, controllers, views, testing, authorization, database, jobs.

Beyond Rails

The marketplace has two other plugins:

hustler-studio (coming soon): Project-agnostic workflows for TDD, refactoring, planning, and quality gates. Adapts to your conventions by reading your project’s CLAUDE.md and rules.

prompting: Prompt writing and optimization. Stack-agnostic.

The Pattern for Other Stacks

Composable rules aren’t Rails-specific. The pattern works for any framework: detect dependencies, copy relevant rules.

Someone could build this for Django, Laravel, Next.js, NestJS, Phoenix, FastAPI. Same pattern, different dependency detection.

If you want to collaborate on adding support for more gems or building plugins for other stacks, the marketplace is open.

Getting Started

Install the marketplace:

/plugin marketplace add bcasci/hustle-marketplace

Install the Rails plugin:

/plugin install hustler-rails

Bootstrap your project:

/hustler-rails:init

You’ll get composable rules tailored to your dependencies.

Want to Contribute?

Think more rules should be added? Have different architecture preferences? Build your own plugin following the same pattern, or collaborate with me to add it to this marketplace.

Check out the repo: https://github.com/bcasci/hustler-marketplace

Building a Production App with AI: The Boswell Story

2025-10-24T02:09:00+00:00

2025-10-23

Building a Production App with AI: The Boswell Story

You see a lot of “AI-First” success stories floating around. Weekend builds that turn into six-figure SaaS products. Solo developers shipping faster than funded teams. Instant revenue from AI-generated apps.

This isn’t that story.

This is a breakdown of what AI-first product development actually looked like for me, and it wasn’t a straight line.

How I Got Here

I co-founded Boswell in 2017. It’s software for community food banks and social service organizations. It helps them track their client services, manage distributions, and effortlessly report data to grantors. We raised grants and impact capital, but the company meandered on mission, caught between what customers actually wanted and grant obligations. Eventually it shut down.

Then I got a surprise offer: take the assets for free at the end of June 2025.

Why not? I knew the product. It had existing customers. I felt that it had potential to be refocused as a SaaS product to specific types of Community Based Organizations. My consulting contract had ended. I was recovering from a health condition and needed time off, but wanted something to focus on. This gave me both.

What I Inherited

The codebase from the later engineering teams was a mess:

Arbitrary dependency hacks to avoid updates
“Reactified” areas that worked fine with server-side rendering
Competing architectures creating unnecessary complexity
Data issues stemming from poor understanding of relational databases

The first sign something was really wrong: users were experiencing slow reports. The previous team’s solution was expensive computing resources and scheduled overnight runs.

My fix? A few database indexes.

Result: 75% cost reduction immediately.

But now I had to face the bigger mess.

The Decision

I weighed fixing mistakes versus starting over. I tried a cleanup approach with Cursor first. It’s fine for autocomplete but struggled with multi-step tasks. Then I tried Roo Code and Roo Code with SPARC. The issue with Roo Code ultimately came down to the per-request costs of cloud models and the limitations of local models.

I switched to Claude Code and had it analyze the problems, then attempted git reverts of the indulgent changes.

Conclusion: rewrite was the better call.

This is where I really learned Claude Code: how to transform myself into a dev team using specialized AI agents.

Validating the Market

Before committing to a rewrite, I validated the opportunity. I didn’t want to rebuild something nobody wants.

I talked to prospective customers about their current pain points. Touched base with users of the old app to understand what worked and what didn’t. Gathered competing products in the community organization space and had AI analyze public information about them. Used AI to help identify which features deserved focus and dialed in what behaviors mattered most to the target market.

The AI advantage here was rapid competitive analysis and pattern recognition across multiple products. It synthesized customer feedback into actionable insights and helped prioritize feature development.

The result: confirmed market need, identified differentiation opportunities, and made the rewrite decision with confidence.

AI-First Isn’t Instant

The upstart cost is real. Efficiency gains have a learning curve.

Out of the gate, the AI was unfocused and over-eager. Getting it to stay on task is harder than it seems. Prompting matters. Workflows matter. Guardrails matter.

Gains come faster on greenfield projects. Legacy code, especially where consistency lacks, requires more work upfront to get AI productive.

What Worked

Domain Knowledge Is the Foundation

I provide patterns and anti-patterns explicitly. Articulate rules and conventions clearly. Document what the app does and why. This helps AI serve customers better, not just write code.

This is the knowledge infrastructure that makes AI accurate. Without it, AI will apply common practices that might not fit your needs, add abstraction layers you don’t want, and miss requirements unique to your system.

Know AI’s Actual Strengths

AI is better at: - Analyzing - Brainstorming - Planning - Being a soundboard

It’s less reliable at writing production-ready code on the first pass. But you can use its strengths to have it write better code.

The Workflow That Works

At a minimum you need a workflow that plans, executes, reviews, and iterates.

You must be involved in planning. You can use AI to generate plans, but you have to be involved in curating them at minimum. Then AI implements. Then you must be involved in review. Respond to reviews, iterate.

Eventually you can hand off more planning and reviews to autonomous workflows. Validate kickoff plans and spot-check reviews. Drift happens even with guardrails. Lengthen the leash gradually.

When things break down, execution problems usually point to planning gaps or knowledge gaps. Too many review cycles with naive mistakes indicate planning or knowledge issues. Use these as opportunities to improve documentation, knowledge, and workflows.

Controlling AI

They Will Try to Escape

Without constraints, your AI helpers will lie, be lazy, jailbreak constraints, and countermand your instructions.

Simplified example: I limited one agent to Read Only by taking away direct Write access to files. Instead, it used console-based editors along with I/O redirection to manipulate files. You need to be very intentional with permissions.

What Keeps Them in Line

Be intentional and direct. Less is more, only as verbose as needed. Break large tasks into smaller ones.

This is how specialized agents stay focused through orchestration and clear boundaries.

The Composability Advantage

Claude Code’s framework gives you custom slash commands, custom skills (new to Claude as of 10/16/2025), custom sub-agents, and hooks for external tools.

The result: reusable components that improve accuracy over time.

Tools and Tactics

Screenshots

Very helpful for debugging and bringing concepts to life. Caveat: make clear when it’s a concept or wireframe versus literal implementation. Otherwise AI will build what’s in the picture, not what you meant.

Third-Party Caution

Avoid third-party plugins at first. They can do anything, which is a security risk. You won’t learn the fundamentals. Resist the “$299 course secrets” temptation. Master the basics first with documentation and other people’s shared experiences.

The Investment

Several times I spent days fine-tuning Claude Code to solve something I could have done manually in 15 minutes. The problem felt like a repeatable pattern worth automating. Each time I invested in understanding how to effectively direct AI, those strategies worked across other projects.

Was it worth it?

Yes, but with context. I had time to burn after my contract ended. Recovering from a health challenge gave me flexibility to work at my own pace. These were my own projects, so I could experiment without client pressure. Not everyone has this luxury. Limited time forces you to prioritize what automation to invest in. Maybe I over-indulged.

Where It Stands Now

I can automate modest changes and bug fixes with sentences or screenshots. Fire them off locally or via GitHub issue. A @claude fix this comment implements automatically.

I was able to move faster on advanced features that would normally have taken quite a bit more time, like complete data isolation between clients and event-based email automation for onboarding and lead nurturing. The kind of operational conveniences I’d usually put off for “phase 2” or later, but got built in phase 1.

The bigger picture: three projects running AI-first workflows. Boswell for community based organization management, plus two others where the same techniques apply.

Perspective on AI and Business

The Reasonable Skeptics

Some people are skeptical of AI adoption, and honestly, they have a point:

It’s a wild beast requiring close attention
It amplifies everything: skill, knowledge, mistakes, and bad intentions
Corporations using it to optimize profit over fairness (UnitedHealth’s AI denying claims, insurers terminating policies based on flawed models)

The Opportunity

If you’re skeptical or just uncertain how AI applies to you, flip the question: if AI could threaten your job or livelihood, can you use it first? The sword cuts both ways. Use it to build revenue streams beyond a paycheck. I did this with rental properties a while back, and AI-assisted product building is way easier in a lot of ways.

If you know something deeply, package it as a product or service. It’s possibly easier now than ever.

Small vs Large Organizations

Individuals and small companies may have an advantage for now:

Smaller scope, easier to automate
More willing to experiment and pivot
Risks easier to manage
Lower bar for success (revenue and cost-savings wise)
Less institutional overhead
Requires whole-organization effort for full benefit, meaning fewer people to convince, especially if you’re one person

Large corporations might struggle:

AI mandate without guidance
Slower to change
Staff resistance
Higher risk profile
More to break
Harder to detect unintended consequences

Where I Stand

I’m comfortable with these tools personally. I’m not automating every aspect of life. I really like them for solo and small business work.

Boswell is live, serving customers, and actually helping community organizations skip the paperwork and get back to serving people. The platform tracks 50K+ household assistances each month, 1.2M total to date. The rewrite worked. The AI-first approach delivered.

It required investment: time to learn the tools, money to burn through API costs, and patience to build the knowledge infrastructure that makes AI accurate. The weekend-build-to-riches stories happen, but they’re rare. You hear about the few that succeed, not the millions that don’t. This took months: trying several AI tools, giving each a fair evaluation, experimenting with Claude Code plugins and addons, then stripping away dependencies to build workflows that actually worked.

The payoff: strategies and skills that accelerate my current business, apply to future ones, or make me more valuable to any employer.

My AI Organization Ships Like We're Funded, But It's Just Me (Part 1)

2025-09-25T04:00:00+00:00

2025-09-25

My AI Organization Ships Like We’re Funded, But It’s Just Me (Part 1)

Part 1: The Knowledge Infrastructure

I ship at the velocity of a funded startup, but it’s just me. The difference is giving AI assistants the same domain knowledge a human team member would have.

I’m not working harder or using productivity hacks. I’m helping AI move from a coding intern into something that can reason about product engineering and business knowledge.

The Evolution So Far

How One Person Becomes a Dev Team with Claude Code - 5 specialists working in parallel
From Dev Team to Engineering VP with Claude Code - Learned to orchestrate, not code
This article - The knowledge infrastructure that makes AI accurate

The Difference That Domain Knowledge Makes

Without your specific context, AI will:

Apply common practices that might not fit your needs
Add abstraction layers you don’t want
Miss requirements unique to your system
Suggest solutions that violate your constraints

But when you document your domain knowledge:

Your product helps [specific customer type] do [specific thing] better
Customers stay because of [key differentiator], not features
Variable names match what the business calls things (not generic “item” or “data”)
“Good code” here means readable over clever, explicit over abstract
That database choice was about compliance, not performance
Multi-tenant isolation is non-negotiable due to [specific requirement]
Past mistakes that shouldn’t be repeated
The architecture patterns you actually strive for

Now AI makes the right architectural decisions without you explaining everything every time.

The Knowledge Infrastructure

Start with a Root CLAUDE.md

Here’s a reduced example from a production Rails app:

# CLAUDE.md - Domain Knowledge for Boswell

## What Boswell Does

- Client management system for food banks and community organizations
- Tracks households, people, distributions, and assistance programs
- Manages eligibility and benefits for food assistance recipients

## Core Architecture

- **Multi-tenant SaaS** with SQLite-per-tenant isolation
- **Tech Stack**: Rails 8, Turbo/Stimulus, Solid Queue, Passwordless auth
- **Real-time**: Turbo Streams and Action Cable for live updates

## Domain Knowledge Distribution

CLAUDE.md files exist throughout the codebase with area-specific guidance. Here are just a few:
- `app/models/CLAUDE.md` Model patterns and database architecture
- `app/controllers/CLAUDE.md` RESTful patterns and Turbo integration
- `app/business_logic/CLAUDE.md` Command pattern implementation

## Code Navigation

Look for AIDEV-NOTE comments in complex areas - they explain non-obvious decisions and gotchas.

# ... longer example at end of article

Document it once, and it’s available in every coding session.

Add Deep Documentation for Complex Systems

Reference docs by path and Claude Code reads them if needed, or use @path/to/doc.md to always import the full content immediately. Here’s how I documented our payout system:

# Payout System

## Flow
ORDER → RevenueSplit → OrderItem (owner/referrer/platform shares)
                           ↓
                    PayoutSchedulerJob (weekly)
                           ↓
                    ProcessPayoutJob → Stripe Transfer

## Key Design Decisions

**Why weekly batching?**
Reduces Stripe fees and operational overhead vs daily payouts.

**Why PayoutItem junction table?**
Prevents double-payment via unique constraint on [order_item_id, payout_type].

## Troubleshooting
**No payout created?**
- User.find(id).stripe_connect_account_id must exist
- Check for existing PayoutItem blocking re-payment

# ... longer example at end of article

You can import these from any CLAUDE.md, prompt, command, or agent:

## Domain Knowledge
@docs/payout-system.md          # Weekly payment processing logic
@docs/multi-tenant-isolation.md # Critical security boundaries
@docs/compliance-hipaa.md       # Healthcare data requirements
@docs/api-rate-limiting.md      # Customer throttling rules

Import these anywhere: in CLAUDE.md files, prompts, commands, or agent instructions.

Distribute Knowledge Throughout Your Codebase

Each major area gets its own CLAUDE.md file:

# app/models/CLAUDE.md

## Model Inheritance (STI)
class Album < Product  # type = 'Album'
class Track < Product  # type = 'Track'

## Money Handling
monetize :price_cents
# Usage: album.price = Money.new(1000, "USD")  # $10.00

## Common Scopes
scope :published, -> { where(listing_state: "published") }
scope :salable, -> { published.where("release_date <= ?", Time.current) }

## Testing Models
- Test your behavior, not Rails
- Focus on custom methods, complex validations, business rules

# ... longer example at end of article

Leave Breadcrumbs with AIDEV-NOTE Comments

# AIDEV-NOTE: Critical section - must acquire lock
# This prevents the race condition we discovered in issue #234
# See: docs/payment-processing.md section 2.2
# Test coverage: spec/models/payment_spec.rb
def process_refund(amount)
  with_advisory_lock("refund_#{id}") do
    # implementation
  end
end

Explain the non-obvious decisions directly in the code.

Less Prompting, More Accurate Results

Without domain knowledge:

You: "Add partial refund support"
AI: [Creates new PartialRefundsController]
    [Adds refund_amount column to orders table]
    [Direct Stripe API call in controller action]
    [No idempotency handling]
    [Doesn't update revenue reporting]
You: "No, we need to... let me explain our architecture..."

With domain knowledge:

You: "Add partial refund support"
AI: [Updates existing Commands::ProcessRefund to handle amounts]
    [Records in ledger_entries with proper double-entry]
    [Queues background job with idempotency key]
    [Follows the same async pattern as other payment operations]
You: "Good, ship it"

The Compound Effect

Every piece of domain knowledge you add compounds over time. Clean commits and good documentation build on each other, while garbage commits become negative context that confuses future work.

Even with good domain knowledge, AI will make mistakes (you would too). The difference is catching them early:

Create review agents with quality standards
Review before committing
When AI struggles, add the missing context
Write clear specs when starting tasks

I’ve found two main failure points:

Missing domain context - AI doesn’t know your business rules
Ambiguous requirements - “Make it better” means nothing even with perfect context

Simple prompts like “add partial refund support” work when your domain docs define the concepts. For complex changes, write a spec that defines success.

The compound effect is real: each piece of context you add makes the next task easier. Clean as you go, and watch your velocity increase.

How to Get Started

Ask your AI to help create the documentation:

“Generate CLAUDE.md files for each major area of this codebase”
“What areas of this codebase would benefit from domain documentation?”
“Create AIDEV-NOTE comments for the complex sections you found”

When AI struggles with something, that’s a signal. Ask it:

“What context would help you understand this better?”
“Where should we document this concept?”
“Add what you just learned to [file].md, optimized for AI agents, concise but informative”

Use AI to help write the documentation once you’ve identified what’s needed.

Distribute CLAUDE.md files throughout your codebase - one per module, service, or complex area. Many small context files beat one giant file. AI can help identify where to place them.

Coming in Part 2

This is just domain knowledge. Next, I’ll show you how I:

How I manage tickets and issues with AI
The CI/CD setup and PR review process
How code review works when your team is AI

For massive enterprise codebases, you’d need more complex memory management. But this simple approach works great for most projects and requires nothing beyond Claude Code itself.

Document your domain knowledge first. Everything else builds on that foundation.

Reduced Examples From Production

These are the actual knowledge files that turn AI assistants from interns into professionals.

Example: Reduced out of CLAUDE.md from Boswell (CBO Management System)

# CLAUDE.md - Domain Knowledge for Boswell
[NOTE: Production file contains more comprehensive documentation]

This file provides guidance to Claude Code when working with the Boswell repository.

## Project Overview

**Boswell** is a Rails 8 food assistance management system designed for Community Based Organizations (CBOs).

### What It Does

- Client management system for food banks and community organizations
- Tracks households, people, distributions, and assistance programs
- Manages eligibility and benefits for food assistance recipients
- Provides real-time updates for distribution events

### Who It's For

- Food banks
- Community organizations
- Social service agencies providing assistance to households in need

### Core Architecture

- **Multi-tenant SaaS** with SQLite-per-tenant isolation (each org gets its own database)
- **Tech Stack**: Rails 8, Turbo/Stimulus, Solid Queue, Passwordless auth, Pundit
- **Real-time**: Turbo Streams and Action Cable for live updates
- **UI**: Server-side rendering with BeerCSS components

## Development Workflows with Specialized Agents

### Orchestrator Commands

/orchestrators:tdd #<issue_number>        # Full TDD for new features
/orchestrators:implement #<issue_number>   # Direct implementation (faster)
/orchestrators:fix-bug #<issue_number>     # Bug fixes with regression test
/orchestrators:refactor "description"      # Safe refactoring with tests

### Specialized Agents

Use specialized subagents when appropriate for tasks like database migrations, bug diagnosis, code quality checks, and more. These will be auto-invoked based on the task context.

## Domain Knowledge Distribution

Always check for relevant CLAUDE.md for our coding standards, patterns and domain knowledge. The codebase contains many CLAUDE.md files with specialized guidance, here are a few:

- app/models/CLAUDE.md Model patterns and database architecture
- app/controllers/CLAUDE.md RESTful patterns and Turbo integration
- app/business_logic/CLAUDE.md Command pattern implementation
- app/policies/CLAUDE.md Authorization patterns with Pundit
- test/CLAUDE.md Testing philosophy and anti-patterns

## Essential Commands

# Development
bin/dev                      # Start Rails server
bin/rails console            # Interactive console

# Database
bin/rails db:prepare         # Setup from scratch
bin/rails db:migrate         # Run migrations

# Testing & Quality
bin/rails test               # Run full test suite
bin/rubocop -A              # Auto-fix style issues

[... production file continues with more sections ...]

Example: Payout System Domain Documentation (Reduced out of Harmonic.fm)

# Payout System
[NOTE: Production file contains additional implementation details]

## Flow

ORDER → RevenueSplit → OrderItem (owner/referrer/platform shares)
                           ↓
                    PayoutSchedulerJob (weekly via config/recurring.yml)
                    Finds users with:
                    - Unpaid owner shares (artists)
                    - Unpaid referrer shares (curators)
                           ↓
                    CreatePayoutJob (per user)
                           ↓
                    ProcessPayoutJob → Stripe Transfer

## Key Design Decisions

**Why weekly batching?**
Reduces Stripe fees and operational overhead vs daily payouts.

**Why combine owner + referrer earnings?**
Single transfer per user is simpler and cheaper than separate transfers.

**Why PayoutItem junction table?**
Prevents double-payment via unique constraint on `[order_item_id, payout_type]`.

## Troubleshooting

**No payout created?**

- `User.find(id).stripe_connect_account_id` must exist
- `OrderItem.unpaid_items_for_user(user)` must return records
- Check for existing `PayoutItem` blocking re-payment

**Stripe transfer failed?**

- Check Stripe Connect account status in Stripe Dashboard
- Verify platform has sufficient balance
- Review `Payout.last.error_message`

## Entry Points

- Schedule: `config/recurring.yml` → `payout_scheduler`
- Manual: `PayoutSchedulerJob.perform_now`
- Per-user: `Commands::CreatePayout.new(user: user).run`

[... production file continues with more details ...]

Example: Reduced Model-Specific CLAUDE.md

# /app/models/CLAUDE.md
[NOTE: Production file includes complete pattern library]

# Model & Database Patterns

## Best Practices

1. **Use scopes**: Named queries for readability
2. **Callbacks**: OK for same-model operations, avoid cross-model callbacks
3. **Commands for business logic**: Multi-step operations across models belong in Commands
4. **Index foreign keys**: Essential for performance
5. **Use concerns**: Extract shared behavior
6. **Validate data**: At database and model level
7. **Test your behavior, not Rails**: Focus on custom methods, complex validations, and business rules

## Common Models

- `User` - Authentication via Passwordless
- `Tenant` - Multi-tenant organization (food bank/CBO)
- `Household` - Family unit receiving assistance
- `Person` - Individual member of household
- `Distribution` - Distribution of assistance event
- `AssistanceProgram` - Programs offered (SNAP, WIC, etc.)
- `Allocation` - Resource assignments
- `Role` - User permissions within tenant
- `TagVocabulary` & `AllowedTag` - Flexible tagging system

## Model Inheritance (STI)

    class Product < ApplicationRecord
      # Base class for all products
    end

    class Album < Product
      # type = 'Album'
      has_many :tracks, foreign_key: :parent_id
      has_one :album_variant
    end

    class Track < Product
      # type = 'Track'
      belongs_to :album, foreign_key: :parent_id, optional: true
      has_one :track_variant
    end

## Common Patterns

### Scopes

    class Album < Product
      scope :published, -> { where(listing_state: "published") }
      scope :salable, -> { published.where("release_date <= ?", Time.current) }
      scope :newest, -> { order(created_at: :desc) }
      scope :by_genre, ->(genre) { tagged_with(genre) }
    end

### JSONB Metadata

    class Product < ApplicationRecord
      # Access JSONB fields
      store_accessor :metadata,
        :artist_name, :release_date, :duration,
        :track_number, :genre_list

      # Usage
      album.metadata_artist_name = "Artist Name"
      album.metadata_release_date = Date.today
    end

### Soft Delete

    class Product < ApplicationRecord
      include Discard::Model

      # Usage
      album.discard    # Soft delete
      album.undiscard  # Restore
      Album.kept       # Non-deleted records
      Album.discarded  # Deleted records
    end

## Associations

### Has Many Through

    class User < ApplicationRecord
      has_many :organization_memberships
      has_many :organizations, through: :organization_memberships

      has_many :orders
      has_many :purchased_products, through: :orders, source: :product
    end

### Polymorphic

    class Recommendation < ApplicationRecord
      belongs_to :user
      belongs_to :recommendable, polymorphic: true

      # Can recommend albums, tracks, etc.
    end

## Validations

    class Album < Product
      validates :title, presence: true, length: { maximum: 255 }
      validates :slug, uniqueness: { scope: :organization_id }
      validates :price_cents, numericality: { greater_than_or_equal_to: 0 }

      validate :has_items, on: :create

      private

      def has_items
        errors.add(:base, "Must have items") if items.empty?
      end
    end

## Money Handling

    class Product < ApplicationRecord
      monetize :price_cents

      # Usage
      album.price = Money.new(1000, "USD")  # $10.00
      album.price_cents # => 1000
      album.price.format # => "$10.00"
    end

## Testing Models

    class AlbumTest < ActiveSupport::TestCase
      describe "validations" do
        it "requires title" do
          album = Album.new
          refute album.valid?
          assert_includes album.errors[:title], "can't be blank"
        end
      end

      describe "scopes" do
        it "returns published albums" do
          published = Album.published
          assert published.all? { |a| a.listing_state == "published" }
        end
      end
    end

[... production file continues with more patterns and examples ...]

How I Went From Dev Team to Engineering VP with Claude Code

2025-09-23T04:00:00+00:00

2025-09-23

How I Went From Dev Team to Engineering VP with Claude Code

I had a bug that only appeared during parallel processing. It was intermittent, timing-dependent, and the kind that makes you question your life choices.

My issue-diagnosis agent found worthwhile improvements that would stave off issues like this, but couldn’t nail the root cause. After a few attempts I took a crack at it, and then thought: wait a minute. I had just recently created a team of specialists and seeded the project with context and domain knowledge. Is this really what I’m supposed to be using my time for?

Me → Claude → Diagnoser → Fix → Test
                 ↑                 ↓
                 └── Still Broken ←┘
                   (repeat 3x)
                        ↓
                 Debug manually
                        ↓
            "Wait, why am I doing this?"

So I made the sub-agents huddle and figure it out.

claude> Work on issue #234. Use issue-diagnoser, analyst, test-writer, and
        implementer. Collaborate by orchestrating communication between them. 
        You will have to make them aware of each other's findings so they can problem
        solve more effectively.

        Ultrathink about possible causes. Tell each agent to ultrathink
        when analyzing. The previous attempts found real issues but not root cause.

        Once you identify the problem, implement minimal fix to verify. Then have
        the team collaborate on various other optimal solutions. Present me with the
        quick fix, and multiple best-practice approaches so I can decide.

The Agents Worked It Out, Orchestration Can Work On-the-fly

The app involves a multi-tenant architecture with complete data isolation between tenants. There was a very minor issue with a shard-switching resource that manifested when the number of processors was increased. Something not realistic on my laptop.

The solution was simple: a MUTEX. But that’s beside the point.

The sub-agents did all of the heavy lifting and found an obscure problem pretty quickly. Based on what I saw, the orchestration that it cooked up looked something like this:

Issue #234
    ↓
Claude reads issue
    ↓
→ Diagnoser: "shard switching"
    ↓
→ Analyst: "multi-tenant issue"
    ↓
→ Test-Writer: "can't reproduce"
    ↓
 ┌─────────┐
 │ Retry?  │
 │    ↓    │
 └──→ Yes ─┘
    ↓ No
"Reproduced! High CPU count"
    ↓
→ Implementer: "MUTEX fix"
    ↓
Multiple solutions presented
    ↓
I decide

I did have to ask for a refinement on the solution I thought best, but that wasn’t particularly time consuming.

Why This Actually Worked

Three things made this ad-hoc orchestration effective:

1. You have to rally the troops

Claude will automatically delegate to subagents when it makes sense. But if you want specific agents involved at a specific moment, you need to call them out by name. Include phrases like use subagent [name] to be explicit.

Although now I can see the case for a /dev-team-huddle command that would kick off this type of workflow automatically.

2. Subagent definitions need good metadata

The description field is critical. It tells the primary agent what the subagent does, when to use it, and what information needs to be passed to it.

Subagents share NO session information with the primary agent. All the prompting you do, everything in the conversation you see (and don’t see) is not shared with the subagent. That initial prompt the primary agent sends them is all they have to work with.

3. Domain knowledge makes isolated agents effective

My projects are rich with domain knowledge. There are CLAUDE.md files with patterns and anti-patterns in strategic locations. The code has casual documentation in it. More intricate areas have more substantial comments (# AIDEV-NOTE: …). Then for fundamental concepts there are stand-alone meta-docs that summarize these topics. These help the primary agent (Claude Code in this case) and the subagents it delegates to. They can navigate and reason about the project much more effectively.

So the sub-agents are set up pretty well even though they’re cut off from the larger conversation. They have the context they need baked into the project.

What These Agents Actually Look Like

The metadata and domain knowledge I mentioned? Here’s what that looks like in practice. These are shortened versions. The production ones have more detail, but you get the idea:

Analyst Agent

---
name: analyst
description: Requirements and architecture analyst who finds patterns and recommends implementation approaches. Pass the complete requirement OR diagnosis from issue-diagnosis. Returns patterns found and architectural guidance. Invoke at start of feature work, planning, or when evaluating bug fix approaches.
tools: Read, Grep, Glob
model: inherit
---

You are a requirements and architecture analyst responsible for understanding features and recommending implementation approaches.

## Core Philosophy

**IMPORTANT: Prioritize correctness and comprehensive solutions over implementation speed.**

- AI can implement quickly regardless of approach
- Test runtime differences are negligible
- **ULTRATHINK**: Think deeply about the best long-term solution
- Consider multiple layers of testing when gaps exist
- Strategic decisions matter more than tactical optimizations

## Scope

**I analyze and recommend:**

- Requirements and GitHub issues
- Bug fix approaches (when given diagnosis from issue-diagnosis)
- Existing patterns in codebase
- Implementation approaches (both for existing patterns and new capabilities)
- Which files need modification
- System architecture decisions
- Comprehensive test strategies across all layers (unit/integration/system)

**I don't:**

- Write code (I'm read-only)
- Run tests or review code
- Implement the decisions (I recommend, others implement)
- Diagnose bugs (that's issue-diagnosis's job)

_[Full production version includes detailed output formats, examples, and comprehensive workflow details]_

Issue Diagnosis Agent

---
name: issue-diagnosis
description: Analyzes bug reports to identify root cause and test gaps. Pass "issue #XXX" or a bug description with affected UI and symptoms. Returns diagnosis only - does not prescribe solutions.
tools: Grep, Read, Bash, Glob
---

## Purpose

Read-only diagnostic specialist. Find root causes and identify test gaps. Do NOT prescribe solutions - only diagnose problems.

## Input

Accept either:

- `issue #XXX` - fetch with `gh issue view XXX`
- Bug description with UI location and symptoms

## Workflow

1. **Find the bug** - Locate where it manifests in code
2. **Trace root cause** - Follow data/logic flow to actual problem
3. **Check ALL test coverage** - Use Glob to find test files at every layer
4. **Identify ALL gaps** - Report missing tests at each affected layer

## Critical Thinking About Test Placement

**Think carefully:** Where does this bug ACTUALLY manifest? Match the test to the bug's location:

- **UI/Visual bug** (wrong text shown, button doesn't work) → **System test gap**
- **Business logic bug** (calculation wrong, validation missing) → **Model/Command test gap**
- **Authorization bug** (user can access forbidden resource) → **Policy test gap**
- **HTTP bug** (wrong status code, missing redirect) → **Controller test gap**

**Key principle:** Match tests to where problems exist. A single bug might expose gaps at multiple layers - report them all if they're legitimate gaps.

_[Full production version includes detailed output templates, pattern recognition rules, and comprehensive diagnostic procedures]_

Test Writer Agent

---
name: test-writer
description: TDD specialist who writes and refines tests. Pass the full requirement, target test files, patterns found, and any validator errors. Invoke when needing tests written or fixed.
tools: Read, Write, Edit, MultiEdit, Grep, Glob
model: inherit
---

You are a TDD specialist responsible for creating and modifying tests ONLY.

## Specialization

This agent creates all test types:

- **Model tests** - validations, scopes, methods
- **Controller tests** - HTTP responses, redirects
- **Job tests** - background job behavior
- **Command tests** - business logic testing
- **Query tests** - database query logic
- **System tests** - UI interactions, browser workflows

## Scope

**I write:**

- New test files (all types)
- Failing tests for TDD (Red phase)
- Test modifications based on validator feedback
- Test syntax fixes

**I don't:**

- Write production code
- Run tests
- Make implementation decisions

## Critical Rule: Test the Actual Bug Scenario

When creating tests for bug fixes, choose the right approach:

**Missing Coverage Tests (Preferred)**
Test what SHOULD happen - the intended behavior that would have prevented the bug.

**Bug Reproduction Tests (When Needed)**
Test the exact failure when you need to prove the bug exists.

_[Full production version includes detailed troubleshooting guides, output formats, and comprehensive testing patterns]_

Implementer Agent

---
name: implementer
description: Implementation specialist who writes production code to pass tests. Pass failing test output, all files to modify, patterns to follow, and current state. Invoke when test is failing correctly.
tools: Read, Write, Edit, MultiEdit, Grep, Glob
model: inherit
---

You are an implementation specialist responsible for writing production code to make tests pass.

## Scope

**I implement:**

- Production code to pass failing tests
- Minimal code for TDD (Green phase)
- Following existing patterns

**I don't:**

- Write tests
- Run tests
- Add extra features beyond test requirements
- Refactor unless needed to pass test
- Create database migrations (return NEEDS_MIGRATION status)

## Process

1. **Understand failing test**

   - What behavior does it expect?
   - What assertion is failing?
   - What's the minimal fix?

2. **Find patterns** (unless trivial fix)

   - Check CLAUDE.md in relevant directories
   - Find 2-3 similar implementations
   - Look for # AI: comments in existing code

3. **Write minimal code**
   - Just what's needed to pass test
   - Follow patterns from existing code closely
   - Use THIS project's patterns, not generic Rails patterns

_[Full production version includes detailed output formats, delegation patterns, and comprehensive implementation guidelines]_

The Transformation

Remember that moment: “Wait, why am I doing this?”

That’s when I realized I’d already built the team. Now I needed to actually use it like one. Instead of jumping back into debug mode myself, I could orchestrate specialists who were setup for these specific problems.

The bug got fixed. But more importantly, I stopped being the bottleneck. When the next complex issue appeared, I knew exactly what to do: rally the team, give them context, let them work.

Your pre-built orchestrators handle routine work. But when something weird comes up, you’re not stuck. You have a team of specialists ready to dive deep while you stay focused on the bigger picture.

You’re not just coding anymore. You’re running an engineering organization where each specialist is made of intentional instructions.

#AICodingAssistants #ClaudeCode #Automation #Productivity #SoftwareEngineering #DigitalTransformation

How One Person Becomes a Dev Team with Claude Code

2025-09-21T16:28:00+00:00

2025-09-21

How One Person Becomes a Dev Team with Claude Code

I wanted to augment my productivity. GitHub Copilot worked for single lines. Then Claude Code and Cursor promised a “pair programmer”, but out of the box they delivered an eager helper with a paintbrush in one hand and a sledgehammer in the other. I got Jackson Pollock and Gallagher rolled into one.

I tried add-on orchestration frameworks for Claude Code next, hoping for a short-cut. Each one added more abstraction layers and created a familiar mess with astonishing speed. Meanwhile, I smelled the YouTube AI influencers before I saw them. Selling parlor tricks to solve staged toy problems that funnel people toward a $299 course to learn the “secrets.” No thanks.

Here’s my truth: AI tools like Claude Code are power tools. They require investment: time to actually read the important parts of the documentation, and money to burn while learning. Without proper boundaries, they’ll waste both your time and money.

This article shows how to multiply your efforts with Claude Code by following their own documentation and best practices. Try this BEFORE reaching for third-party add-ons. It’s just a simple folder structure with carefully groomed contents that turn one person into a team.

The Problem Everyone Knows, But Few Seem To Address

You’ve been there. You ask Claude to fix a login bug. Twenty minutes later, it’s refactored your entire auth system, added three dependencies you didn’t ask for, and is halfway through writing migration guides for features that don’t exist yet.

Without boundaries, Claude fabricates its own priorities. You asked for a bug fix, you got a redesign, and probably a broken one.

You know the pain:

Complex tasks drift off course without persistent focus on the goal
Same prompt, different day, wildly different approach
Linear instructions fail because AI wanders into tangents
The assistant “helps” by adding improvements you’ll spend hours removing

The solution isn’t just better prompts with clear intent. It’s orchestration.

The Architecture: Just Folders and Files

Forget complex frameworks. This entire system is folders and markdown files that Claude Code already knows how to read:

.claude/
├── agents/
│   ├── dev-team/               # Your specialized team members
│   │   ├── analyst.md          # Requirements & architecture
│   │   ├── test-writer.md      # Writes comprehensive tests
│   │   ├── implementer.md      # Writes production code
│   │   ├── validator.md        # Runs tests & linting
│   │   └── reviewer.md         # Pattern compliance
│   │
│   ├── check-quality.md        # Independent quality auditor
│   └── issue-diagnosis.md      # Bug root cause analysis
│
├── commands/
│   └── orchestrators/          # High-level workflows
│       ├── tdd.md              # Test-driven development flow
│       └── fix-bug.md          # Debugging workflow
│
└── protocols/                  # Shared standards
    ├── agent-output-protocol.md
    └── scratchpad-protocol.md  # State management

That’s it. No npm packages. No Python libraries. Just markdown files that tell Claude Code how to behave in specific contexts. If you want to get fancy, do that later.

The Cast of Characters: Specialized Agents

Instead of one AI assistant trying to do everything, you create specialists. Each agent has a narrow scope and explicit boundaries.

Here’s what the implementer.md agent looks like (simplified from production):

---
name: implementer
description: Implementation specialist who writes production code to pass tests
tools: Read, Write, Edit, MultiEdit, Grep, Glob
---

# Implementer Agent
# Note: Simplified for this article. Production version has more directives.

You write production code following established patterns and requirements.

## Your Scope

**You DO:**
- Write minimal code to make tests pass
- Follow patterns from domain-specific CLAUDE.md files
- Use existing conventions and helpers
- Keep implementation focused on requirements

**You DON'T:**
- Write tests (that's test-writer's job)
- Add features not required by tests
- Refactor unrelated code
- Make architectural decisions

Notice the explicit boundaries. The implementer can’t write tests. That’s someone else’s job. It can’t add features the tests don’t require. This constraint is what makes it a lot more reliable.

My current team roster:

Analyst: Breaks down requirements, identifies affected files
Test-Writer: Creates test coverage before implementation
Implementer: Writes the minimal code to pass tests
Validator: Runs tests and linting
Reviewer: Checks patterns and standards

There are actually more for research, marketing, UX, product advice. You can hire and fire specialists as you see fit for your own projects.

Each agent can fail. That’s expected and handled by the orchestrator.

Gates: Why Non-Linear Workflows Work

Traditional AI workflows are brittle. One failure stops everything:

START → Step 1 → Step 2 → Step 3 → END
         ↓ fail    ↓ fail   ↓ fail
        STOP      STOP      STOP

Gate-based flows self-heal. Each gate is a checkpoint that can retry with different approaches:

┌──────────────────────────────────────────────────────┐
│  GATE 1: Analysis                                    │
│  ├─ Try analyst agent                                │
│  ├─ Fail? → Try again with more context              │
│  └─ Pass? → Gate 2                                   │
├──────────────────────────────────────────────────────┤
│  GATE 2: Write Test                                  │
│  ├─ Simple? → Orchestrator writes it                 │
│  ├─ Complex? → Delegate to test-writer               │
│  ├─ Fail? → Loop with fixes                          │
│  └─ Pass? → Gate 3                                   │
├──────────────────────────────────────────────────────┤
│  GATE 3: Implementation                              │
│  ├─ Try implementer                                  │
│  ├─ Tests fail? → Fix and retry                      │
│  └─ Tests pass? → Gate 4                             │
└──────────────────────────────────────────────────────┘

Each gate can loop internally until satisfied. Circuit breakers prevent infinite loops. A scratchpad file maintains state across attempts, so agents learn from previous failures.

This isn’t theoretical. Here’s actual gate logic from the TDD orchestrator:

### Gate 4: GREEN Phase (Make Tests Pass)

**Goal: Minimal implementation to make tests pass**

- Simple (under 10 lines): Implement yourself
- Complex: Delegate to implementer agent
- Run tests to verify they PASS
- If tests fail → Determine root cause:
  - Implementation incomplete → Continue
  - Test was wrong → Back to Gate 3
- Log GREEN phase completion to scratchpad

The orchestrator decides at each gate: simple enough to do myself, or delegate to a specialist? Failed attempt? Loop with more context or try a different approach.

Domain Knowledge: The CLAUDE.md Files

Your codebase already has patterns. The CLAUDE.md files capture them:

Project Root/
├── CLAUDE.md                    # Project-wide patterns
├── app/
│   ├── models/CLAUDE.md        # Model patterns & anti-patterns
│   ├── controllers/CLAUDE.md   # Controller conventions
│   └── business_logic/CLAUDE.md # Command patterns
└── test/
    └── CLAUDE.md                # Testing standards

These aren’t vague guidelines. They’re specific instructions:

# app/controllers/CLAUDE.md
# Note: Production version is 200+ lines with detailed patterns

...(earlier patterns)...

## Anti-Patterns (NEVER DO)

### Missing Authorization
# BAD - No authorization
def show
  @post = Post.find(params[:id])
end

# GOOD - Always authorize
def show
  @post = policy_scope(Post).find(params[:id])
  authorize @post
end

### Business Logic in Controllers
Complex logic belongs in Commands, not controllers.

...(more patterns below)...

When the implementer agent runs, it reads these files and follows the patterns. No more explaining your codebase conventions every time.

Example: The TDD Orchestrator in Action

Here’s what happens when you type /orchestrators:tdd #234:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Analyst   │ →   │ Test-Writer │ →   │ Implementer │
└─────────────┘     └─────────────┘     └─────────────┘
       ↓                    ↓                    ↓
  "2 files,            "Test for         "Make it pass"
   3 methods"          each method"
                            ↓                    ↓
                      ┌─────────────┐     ┌─────────────┐
                      │  Validator  │ →   │   Reviewer  │
                      └─────────────┘     └─────────────┘
                         "Run tests"      "Check patterns"
                            ↓                    ↓
                        Tests Pass?         Clean Code?
                         No → Loop          No → Fix
                         Yes → Next         Yes → Done

The orchestrator manages the entire flow:

Creates a scratchpad file for state management
Delegates requirement analysis to the analyst
Decides if tests are simple enough to write directly or need the test-writer
Runs the implementer to make tests pass
Validates with test runs
Reviews code quality
Runs full test suite to catch regressions

If any step fails, it loops with more context. The scratchpad maintains history so each retry learns from previous attempts.

When This Approach Shines

It works best when you have:

Clear requirements - A GitHub issue with acceptance criteria
Existing patterns - Similar code in your codebase to follow
Well-defined CLAUDE.md files - Domain knowledge documented
Scoped work - Features that fit in a few files
Repetitive patterns - CRUD operations, API endpoints, test suites

Don’t use this for greenfield architecture decisions or exploratory coding. Use it to multiply your output on well-defined work. Plan first.

Limitations and Common Failures

Things to Watch

Context window usage - The scratchpad grows with each gate attempt. Complex tasks could hit limits, but you could mitigate that with further task decomposition.

API costs - Multiple agent calls add up in terms of tokens. Something to consider if you per per request or token.

Architecture decisions - The worker agents follow patterns, they don’t create them. Design first, then delegate. With that being said, you can automate quite a bit of planning in preceding workflows.

Common Failure Modes

Analyst gets lost in large codebases. Solution: Add specific context files file paths to the prompt. Ask your agens if it needs addtional documentation to avoid future confusion.

Test-writer creates tests that pass without implementation. The validator gate catches this and retries.

Implementer adds unnecessary complexity. Adjust the contraints to cut down on iterations with the reviewer agent. Thoguh the reviewer agent, and broader check-quality agent, will catch issues and send them back for simplification.

Same error keeps repeating. Circuit breaker activates after 3 attempts, escalates to you.

Implementation Lessons

What Works

Small, focused agents. Be only as verbose as you need to be.

Explicit gates with clear success criteria.

Self-healing loops that retry with context.

Scratchpad files that maintain state across attempts.

Domain-specific patterns that encode your conventions.

What Doesn’t

One agent to rule them all. Specialist agents are more reliable, at the cost of speed.

Linear workflows. Gates and loops handle real-world complexity.

Vague success criteria. “Make it work” isn’t enough, be explicit.

Fighting the helpful nature. Use boundaries, and again, clear instructional prompts.

Next Level: Hooks and Extensions

Once the basic system works, you can add:

┌──────────────────────────────────────────────────────┐
│  Claude Code Hooks:                                  │
│  • pre-tool-hook: Validate before edits              │
│  • post-tool-hook: Auto-run tests after changes      │
│  • submit-hook: Block if tests failing               │
├──────────────────────────────────────────────────────┤
│  External Integrations:                              │
│  • CI/CD triggers (run orchestrators on PR)          │
│  • Custom validation scripts                         │
│  • Domain-specific gates                             │
└──────────────────────────────────────────────────────┘

But start simple. Get the agents working first.

Key Diagrams for the Article

The full system architecture:

┌─────────────────────────────────────────────────────────────┐
│                     DEVELOPER (You)                         │
└──────────────────────┬──────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────────────┐
│                  ORCHESTRATOR COMMAND                       │
│              (/orchestrators:tdd #234)                      │
└──────────────────────┬──────────────────────────────────────┘
                       ↓
        ┌──────────────┴──────────────┐
        ↓                             ↓
┌───────────────┐            ┌────────────────┐
│     GATES     │            │   SCRATCHPAD   │
│  (Checkpoints)│←──────────→│ (State Memory) │
└───────┬───────┘            └────────────────┘
        ↓
┌───────────────────────────────────────────┐
│            SPECIALIZED AGENTS             │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐      │
│  │Analyst  │ │T-Writer │ │Implement│      │
│  └─────────┘ └─────────┘ └─────────┘      │
│  ┌─────────┐ ┌─────────┐                  │
│  │Validator│ │Reviewer │                  │
│  └─────────┘ └─────────┘                  │
└───────────────┬───────────────────────────┘
                ↓
┌───────────────────────────────────────────┐
│         DOMAIN KNOWLEDGE (CLAUDE.md)      │
│   • Project patterns                      │
│   • Anti-patterns to avoid                │
│   • Testing standards                     │
│   • Code conventions                      │
└───────────────────────────────────────────┘

Example Files (Simplified from Production)

These are reduced examples extracted from a working production system. The real ones are more verbose with additional error handling, but these show the core patterns:

Example Files

Project Structure Files

File	Purpose
`.claude/commands/orchestrators/tdd.md`	TDD orchestrator with gate logic
`.claude/commands/orchestrators/fix-bug.md`	Bug-fix workflow pattern

Agent Definitions

File	Purpose
`.claude/agents/dev-team/analyst.md`	Requirements analyzer
`.claude/agents/dev-team/test-writer.md`	Test creation specialist
`.claude/agents/dev-team/implementer.md`	Production code writer
`.claude/agents/dev-team/validator.md`	Test runner
`.claude/agents/dev-team/reviewer.md`	Code quality checker
`.claude/agents/check-quality.md`	Independent quality auditor
`.claude/agents/issue-diagnosis.md`	Root cause analyzer

Protocols & Standards

File	Purpose
`.claude/protocols/agent-output-protocol.md`	Communication format
`.claude/protocols/scratchpad-protocol.md`	State management rules

Domain Knowledge

File	Purpose
`app/models/CLAUDE.md`	Model patterns
`app/controllers/CLAUDE.md`	Controller conventions
`test/CLAUDE.md`	Testing standards

Note: Production versions include more detailed error handling, retry logic, and domain-specific rules. Start with these to understand the pattern.

Claude Code Power Features Used

This approach leverages several documented Claude Code features:

Subagents - The foundation of orchestration
Custom Slash Commands - Creating /orchestrators:tdd style commands
CLAUDE.md Files - Domain knowledge injection
Hooks - Pre/post tool validation (optional enhancements)
Prompt Engineering - XML tags, think/ultrathink directives for complex reasoning

Read these docs first. They’re the difference between fighting the tool and wielding it.

Conclusion

One person with clear vision can orchestrate an entire development workflow through clear prompts, structure, and boundaries.

Gates break complex work into verifiable checkpoints. Delegation to specialists solves the focus problem. The scratchpad becomes your feedback loop for continuous improvement.

Stop fighting your AI assistant. Start orchestrating your AI team.

Big problems become manageable when you decompose them into specialist-sized chunks. A folder structure and some markdown files can turn one developer into five who actually stay in their lane.

The tools are already there in Claude Code. You just need to arrange them properly.

How We Automated GitHub Issues with Free AI

2025-08-24T05:00:00+00:00

2025-08-24

How We Automated GitHub Issues with Free AI

Building on the foundation: This artist is an extention to teaching Claude Code to be consistent and turning prompts into reusable commands. If you’re new to CLAUDE.md files, start there.

We’re a small team that runs everything through GitHub Issues. I’d already invested in Claude Code Pro and documented our patterns with CLAUDE.md files. That setup was working great for complex development.

But I kept seeing routing simple tasks pile up - the kind that take 5 minutes to fix but 30 minutes of context switching. I wanted to delegate these without adding another subscription.

So I setup a two-tier system: Claude handles the complex work, and free Gemini takes the simple stuff. Both read from the same CLAUDE.md files, so the code stays consistent.

Now when someone reports a small change or bug, we comment @gemini-cli fix this and get back to work. Gemini creates the branch, fixes the issue, runs tests, and opens a PR.

Why This Made Sense

Simple Tasks Are Perfect for Automation

Simple tasks usually have a well-defined scope, and if not, then they can be easier to define. “Change button color to …” or “Update docs for endpoint” - these have clear boundaries. They’re low risk, easy to review, easy to revert if needed. Clear success criteria too - tests pass, issue closed.

These tasks add up to real time over weeks. And since we already documented our patterns in CLAUDE.md files, they apply directly.

Building on What We Had

Claude Code Pro was already handling complex development. CLAUDE.md files had our patterns documented and proven. GitHub Issues provided a natural queue for work items. The next logical step was to automate the automatable.

How We Split the Work

Claude Code handles complex features, pair programming, architecture work. Gemini (free) takes simple fixes, test updates, documentation, routine changes. Both use the same patterns from CLAUDE.md, so we get consistent code regardless of which AI writes it.

Cost structure stays at $199/month total - no additional subscriptions. Althought you might have need to pay for some requests depending on how frequently you invoke the action.

The Solution: Gemini CLI + Domain Context

Why Gemini?

The free tier covers a lot of ground - we haven’t hit limits yet. There’s a GitHub Action for Gemini CLI that Google maintains. It handles structured tasks well and can execute shell commands reliably.

The Architecture

# Two-tier AI system:
Claude Code Pro → Complex development, architecture decisions
Gemini CLI → PR automation, routine fixes

Initializing Gemini for the Project

Ran gemini /init to create a root GEMINI.md, then curated it to fit the project. After that, I added companion files alongside each CLAUDE.md:

# app/models/GEMINI.md

# Model Patterns

Read this file for rules and patterns.

@./CLAUDE.md

Simple reference - no duplication. Now the project structure looks like:

CLAUDE.md
GEMINI.md
app/business_logic/CLAUDE.md
app/business_logic/GEMINI.md
app/controllers/CLAUDE.md
app/controllers/GEMINI.md
app/models/CLAUDE.md
app/models/GEMINI.md
test/CLAUDE.md
test/GEMINI.md
# ... and so on

Both AIs read the same patterns. Future refactor might extract to AGENT.md, but this works now.

GitHub Actions Setup

Ran gemini /setup-github to generate the workflows in .github/:

Created issue comment handler
Created PR comment handler
Set up Gemini CLI integration

Custom Gemini Commands

Created .gemini/commands/implement.toml for TDD workflow (similar to how I create custom Claude commands):

name = "implement"
description = "Implements a feature or fix according to project patterns"
prompt = """
You are an expert Rails developer implementing a change.

Follow strict TDD process while adhering to patterns in CLAUDE.md files.

Your Process:
1. Analyze the request
2. Consult CLAUDE.md files for patterns
3. Write a failing test
4. Implement minimal code to pass
5. Run tests and linter (bin/rubocop -A)
"""

Now we can trigger from issues:

@gemini-cli /implement - uses issue description
@gemini-cli /implement change tab order - adds extra context
@gemini-cli default the active scope to nil - direct instruction

The Implementation Journey

Phase 1: Initial Setup

# Basic integration
- name: Run Gemini
  uses: google-github-actions/run-gemini-cli@v0

This worked for basic commands, but failed when Gemini tried to run Rails commands. It couldn’t find Ruby or any of the gems - the environment wasn’t persisting between commands.

Phase 2: Solving the Environment Issue

The discovery: Gemini runs commands via bash -c which creates isolated shells. GitHub Actions environment variables don’t persist between commands. But Gemini reads .env files in the working directory.

Added composite action to gemini-cli.yml after checkout:

# .github/gemini-cli.yml
# ...
# I put this after the branch checkout.
# This is a github composite action that contains all the rails app setup steps.
# This composite is used by ci.yml too.
- name: Setup Rails environment
  uses: ./.github/actions/setup-rails-env
  with:
    setup-database: "true"

# For injecting ENV variables into Gemini CLI - is there a better way?
- name: Setup environment for Gemini CLI
  run: |
    touch $GITHUB_WORKSPACE/.env
    cat $GITHUB_WORKSPACE/.github/actions-env/.env >> $GITHUB_WORKSPACE/.env
# ...

This ensures Gemini has everything it needs (Ruby, gems, database) before executing commands.

The static environment file:

# .github/actions-env/.env
# Gemini CLI Ruby/Rails Environment
# These paths must be hardcoded because Gemini runs commands via bash -c
# which creates isolated shells that don't inherit the GitHub Actions environment
PATH=/opt/hostedtoolcache/Ruby/3.3.8/x64/bin:/home/runner/work/commerce_app/commerce_app/vendor/bundle/ruby/3.3.0/bin:$PATH
GEM_HOME=/opt/hostedtoolcache/Ruby/3.3.8/x64/lib/ruby/gems/3.3.0
GEM_PATH=/opt/hostedtoolcache/Ruby/3.3.8/x64/lib/ruby/gems/3.3.0
BUNDLE_PATH=/home/runner/work/commerce_app/commerce_app/vendor/bundle
BUNDLE_APP_CONFIG=/home/runner/work/commerce_app/commerce_app/.bundle
BUNDLE_GEMFILE=/home/runner/work/commerce_app/commerce_app/Gemfile
BUNDLE_DEPLOYMENT=false
BUNDLE_WITHOUT=production

# TODO: Make Ruby version dynamic
# Is there a better solution? Let me know if you find one.

Getting Started

Look at your last 10 closed issues:

Which were trivial but took an hour?
Which cost you focus on bigger problems?
Which were literally just “change this text” or “fix this color”?

Those are your automation targets.

The Minimum Viable Automation

Set up Gemini CLI in ONE workflow
Handle ONE type of issue (e.g., “failing tests”)
Use for one week
Measure: Did it save more time than it took to set up?
If yes, add another issue type
Iterate
- Be mindful of context files. They need curation.
- Experiment with prompting, but don’t get too complex
- Experiment with other models

Why This Works for Small Teams

You can move fast. You can be pragmatic. You already have context. Small products are easier for AI to understand. Your patterns are probably consistent if you have a small footprint, and if not, make them consistent. Your issues are well-defined.

Everyone knows the frustration of losing an hour to a five-minute task because of context switching.

This isn’t about being clever with AI. It’s about being practical with time.

It’s not revolutionary. It’s not magical. It’s just a way to work more efficiently, so you can deliver value in less time.

See It in Action

Triggering Gemini from an Issue

Just comment @gemini-cli on any issue. That’s it.

The Initial Response

Gemini acknowledges the request and starts working.

After the Environment Fix

Once the environment is configured correctly, Gemini executes commands, runs tests, and creates the PR.

Turn Your Best AI Prompts into Reusable Commands

2025-08-04T05:00:00+00:00

2025-08-04

Turn Your Best AI Prompts into Reusable Commands

You’ve documented your patterns with CLAUDE.md files. Claude checks them automatically. Your code is consistent now.

But you’re still typing the same TDD instructions every time you implement something. What if that perfect prompt could be a simple command? What if we could express our intentions for work this way?

/implement #45
/implement Add password reset with email confirmation  
/implement docs/features/search.md
/implement Fix users can't remove items from cart

Each command captures your workflow once, then applies it consistently every time.

The Problem: Great Documentation, Repetitive Instructions

You’ve done the hard work. Root CLAUDE.md with project conventions. Specialized CLAUDE.md files in each directory. Clear patterns and anti-patterns documented. Claude checks these files automatically.

But you’re still repeating yourself:

“Follow TDD - write the test first”
“Check the patterns in app/models/CLAUDE.md”
“Find similar examples with grep”

Same workflow instructions, every single time.

Documentation tells Claude what your patterns are. But not how to apply them consistently. You need to capture your workflow, not just your patterns.

The Solution: Custom Slash Commands

From Anthropic’s docs, custom commands are prompt templates stored as Markdown files. They’re for repeated workflows you use often, stored in .claude/commands/, and can include $ARGUMENTS for dynamic input.

Think of it this way: CLAUDE.md files define what your patterns are. Commands define how to apply them. Together, they make consistency automatic.

The Complete /implement Command

Save this as .claude/commands/implement.md:

---
description: Implement features from issues, PRDs, or direct requests
argument-hint: "#123" or "path/to/plan.md" or "feature description"
allowed-tools: Read, Write, Edit, MultiEdit, Bash, TodoWrite, Grep
---

# Implement $ARGUMENTS

## Step 1: Understand the Request

Look at $ARGUMENTS and figure out what the user wants:
- If it's a number with #, it's a GitHub issue - use `gh issue view` to read it
- If it's a file path, read that file
- Otherwise, it's a direct request - use it as-is

## Step 2: Follow Our TDD Process

Follow the patterns documented in CLAUDE.md files:

1. Write failing test first
2. Implement just enough to pass
3. Verify test passes

Always check relevant CLAUDE.md files for patterns and examples.

Breaking It Down

The frontmatter controls how your command appears and behaves:

description: What appears in the command menu when you type /
argument-hint: Shows users the expected input format
allowed-tools: Grants permissions the command needs to work

Step 1 handles input intelligently. $ARGUMENTS is Anthropic’s built-in way to pass parameters. Simple conditional instructions guide different behaviors. No complex parsing needed.

Step 2 reinforces your workflow. It tells Claude to check CLAUDE.md (which it already does), provides clear sequential steps, and keeps the workflow consistent every time.

The Magic of $ARGUMENTS

One command, infinite flexibility.

GitHub Issue

/implement #45

$ARGUMENTS becomes “#45”
Command fetches and implements the issue

PRD File

/implement docs/prd/search.md

$ARGUMENTS becomes “docs/prd/search.md”
Command reads and implements from PRD

Direct Request

/implement Add user avatars

$ARGUMENTS becomes “Add user avatars”
Command implements the feature

How the Command Works in Practice

Simple model addition

/implement Add published_at timestamp to Article

The command will:

Use “Add published_at timestamp to Article” as the task
Check CLAUDE.md files automatically
Write test for published_at behavior first
Create migration and update model
Verify test passes

Bug fix from issue

/implement #45

The command will:

Run gh issue view 45 to get details
Read: “Users can’t remove items from cart”
Check CLAUDE.md files for patterns
Write failing test first
Implement fix
Verify test passes

Complete feature from PRD

/implement docs/features/wishlists.md

The command will:

Read the PRD file for requirements
Check CLAUDE.md files throughout
Implement with TDD for each component
Follow all your documented patterns

Making It Natural

Add to your root CLAUDE.md:

## Natural Language Implementation

When users say:

- "Create X" → Treat as `/implement X`
- "Add Y" → Treat as `/implement Y`
- "Fix Z" → Treat as `/implement Z`

The /implement command will handle the TDD workflow.

Now “Create a User model” triggers your complete workflow without typing /implement.

Refining Your Workflow

Your initial commands and documentation won’t be perfect. That’s expected.

When you notice patterns you don’t like:

/analyze-workflow

This command:

Checks recent changes against your patterns
Identifies what went wrong
Suggests improvements to commands and CLAUDE.md
Asks before applying changes

Example Refinement Session

/implement Add notification system with audit trail

Result: Test file with 281 lines, nested describes, business logic in model.

/analyze-workflow

Output:

## Pattern Violations Found:

1. **Model Test Anti-Patterns**:
   - ❌ Nested validation describes
   - ❌ Test file too long (281 lines)
   - ❌ Using create! instead of fixtures

### Root Cause Analysis:
- No line limit guidance in test/CLAUDE.md
- Examples don't show flat validation structure

### Suggested Improvements:
1. Update test/CLAUDE.md:
   - Add "50-100 line target" for model tests
   - Show flat validation examples

Would you like me to apply these improvements? (yes/no)

The iteration process:

Run your command - See what it produces
Identify issues - What patterns were violated?
Analyze root cause - Why did it happen?
Update guidance - Improve commands or CLAUDE.md
Test again - Verify improvements work

Your patterns evolve with your codebase. Team preferences emerge over time. Edge cases reveal missing guidance. Continuous improvement beats perfect first attempts.

Why This Works

Commands reference your existing patterns. Documentation ensures consistency. Commands stay focused on workflow.

Your command provides: markdown "Follow the patterns documented in CLAUDE.md files"

This simple instruction builds on Claude’s existing behavior. No complex conditional logic. Works for any implementation type.

Getting Started

Step 1: Create the Command

mkdir -p .claude/commands

Copy the complete command from above into .claude/commands/implement.md

Step 2: Try It

/implement Add Product model with name and price

Watch as it follows your instructions:

Checks patterns
Writes tests first
Implements correctly

Step 3: Refine It

When you see output you don’t like: /analyze-workflow

Apply suggested improvements and try again.

Results and Impact

Before commands:

5-10 minutes explaining each time
Sometimes forget TDD
Inconsistent implementations
Mental fatigue from repetition

After commands:

Consistent implementations
TDD every single time
Follows your patterns
Mental energy for real problems

Once /implement works, create more:

/debug - Systematic debugging process
/refactor - Apply patterns to existing code  
/review - Check against CLAUDE.md patterns
/test - Add tests to existing code

Each leverages your CLAUDE.md foundation.

Key Takeaways

Commands are saved prompts - Anthropic designed them as reusable templates. $ARGUMENTS provides flexibility. Natural language instructions work best.
They complete your documentation - CLAUDE.md = the patterns. Commands = the workflow. Together = consistency.
Simple instructions work - Clear steps get consistent results. Build on Claude’s existing behaviors. No complex logic needed.
Iteration is expected - Start simple. Refine based on output. Use /analyze-workflow to improve systematically.

Try It Yourself

The setup is simple:

mkdir -p .claude/commands

Then copy the /implement command from above into .claude/commands/implement.md.

That’s it. Next time you need to implement something, just type /implement followed by what you want.

Remember: your first command won’t be perfect. That’s fine. Use /analyze-workflow when you see output you don’t like, and refine from there.

The real power comes from combining this with your CLAUDE.md files. Documentation defines the patterns. Commands apply them. No more typing the same instructions every time.

From Chaos to Control: How I Taught Claude Code to be Consistent and Accurate

2025-07-30T05:00:00+00:00

2025-07-30

From Chaos to Control: How I Taught Claude Code to be Consistent and Accurate

I started using Claude Code for Rails development with the same excitement everyone has when they first discover AI coding assistants. The promise was incredible: describe what you want, get working code instantly.

Then reality hit. Suboptimal code. Inconsistent patterns. Going off on tangents when I asked for simple changes. Every implementation looked different. Business logic crammed into models. Tests that just tested Rails itself.

The solution wasn’t to abandon AI - it was to train it properly.

The Problems I Faced

1. Inconsistent Code Style

Every time I asked Claude to create a new model or controller, it was like working with a different developer. No adherence to our conventions. Mixed patterns within the same codebase. One file used service objects, the next stuffed everything into fat models.

2. Reinventing the Wheel

Claude didn’t know our existing patterns. Ask for user authentication? It would create a whole new system instead of using our established AuthenticationService. Need error handling? New approach every time, ignoring our standardized error classes.

3. Suboptimal Patterns & Lost Focus

The worst part was the Rails anti-patterns. Business logic in models. Fat controllers doing five different things. Database queries in views. And don’t get me started on the tangents - I’d ask for a simple model change and get a complete architectural redesign of unrelated parts.

The Solution: CLAUDE.md Files

Quick Win Example

Before diving deep, here’s a simple CLAUDE.md that shows the concept in action:

# Models Directory Rules

Models should be thin. Only include:
- Validations
- Associations  
- Scopes
- Database-related configs

Business logic goes in app/services or app/commands.

Just 7 lines that set clear boundaries. Once Claude reads this, it knows exactly where business logic belongs.

And here’s a companion CLAUDE.md for the commands directory:

# Business Logic Commands

All commands should:
- Inherit from BaseCommand
- Have single public method: call
- Be idempotent when possible (safe to run multiple times)
- Return success() or error() with clear messages
- Handle their own error cases

Keep commands focused on single responsibility unless splitting creates more complexity than it solves.

What They Are

CLAUDE.md files are markdown documents placed strategically throughout your codebase. They’re living documentation that AI reads before acting on any code in that directory. Think of them as executable specifications, not just guidelines.

The Structure

project_root/
├── CLAUDE.md          # Project overview, conventions, architecture decisions
├── app/
│   ├── business_logic/
│   │   └── CLAUDE.md  # Command pattern specs
│   ├── controllers/
│   │   └── CLAUDE.md  # Controller patterns
│   ├── models/
│   │   └── CLAUDE.md  # Thin model rules
│   └── test/
│       └── CLAUDE.md  # Testing patterns & anti-patterns

The root CLAUDE.md contains project overview, critical commands (test, build, deploy), and general intentions. When Claude works on a file, it reads all CLAUDE.md files up the directory tree, so specific coding patterns live close to the code they govern while general project context stays at the root.

Key Components

1. Positive Examples

Show exactly how things should be done with real code from your project:

# GOOD: Thin model
class User < ApplicationRecord
  validates :email, presence: true, uniqueness: true

  has_many :posts
  belongs_to :organization

  scope :active, -> { where(active: true) }
end

2. Anti-Patterns

Be explicit about what NOT to do:

# NEVER DO THIS
class User < ApplicationRecord
  def send_welcome_email
    UserMailer.welcome(self).deliver_later
    update(welcomed: true)
  end
end

3. Context-Specific Rules

When to apply patterns, when exceptions are allowed, how to handle edge cases. Your documentation, your rules.

What This Looks Like in Practice

Without CLAUDE.md Guidelines

Here’s a typical Rails model that mixes concerns:

class Post < ApplicationRecord
  belongs_to :user

  def publish!
    self.published_at = Time.current
    self.status = 'published'
    save!

    NotificationMailer.post_published(self).deliver_later
    user.increment!(:published_posts_count)

    TwitterService.new.share(self) if user.twitter_connected?
    update_search_index
  end

  def archive!
    self.status = 'archived'
    self.archived_at = Time.current
    save!

    remove_from_search_index
    CacheService.expire_post(self)
  end
end

With CLAUDE.md Guidelines

Following the thin model pattern from our example CLAUDE.md:

class Post < ApplicationRecord
  belongs_to :user

  validates :title, presence: true
  validates :content, presence: true

  scope :published, -> { where(status: 'published') }
  scope :draft, -> { where(status: 'draft') }

  # Just data, validations, and associations
end

# In app/commands/publish_post_command.rb
class PublishPostCommand < BaseCommand
  def initialize(post)
    @post = post
  end

  def call
    # Idempotent - safe to run multiple times
    return success(@post) if @post.status == 'published'

    @post.update!(
      published_at: Time.current,
      status: 'published'
    )

    # These operations only happen on first publish
    NotificationMailer.post_published(@post).deliver_later
    @post.user.increment!(:published_posts_count)

    TwitterService.new.share(@post) if @post.user.twitter_connected?
    SearchIndexer.new.index(@post)

    success(@post)
  end
end

The model stays focused on data and relationships. Business logic gets its own home where it’s testable, reusable, and maintainable.

The Implementation Process

1. Audit Existing Code

First, I had Claude analyze my codebase to identify patterns already in use. This gave me a baseline of what was working and what needed fixing.

2. Create Documentation Hierarchy

Started with a root CLAUDE.md for project overview, then added specific files for each major directory. Test documentation got the most detail - that’s where consistency matters most.

3. Make It Actionable

Set clear intentions that AI can follow. The root CLAUDE.md tells Claude WHEN to use patterns:

# Project Architecture (root CLAUDE.md)

... (project overview above) ...

## Command Pattern Usage

Use commands for:
- Any operation that changes system state
- Multi-step business processes  
- Operations that send emails or trigger external services
- Any action that needs to be audited or logged

Do NOT use commands for:
- Simple data queries
- View helpers or presenters
- Configuration or settings

... (other architectural decisions below) ...

While subdirectory CLAUDE.md files show HOW to implement those patterns. This separation lets Claude understand the architecture at the right level - high-level decisions at the root, implementation details where the code lives.

4. Continuous Refinement

As you work with Claude, you’ll discover edge cases and better patterns. Update the documentation. It’s living documentation - let it evolve with your codebase.

Results and Impact

Predictable Output

Every model looks like every other model. Every command follows the same pattern. No more surprises or “creative” implementations.

Faster Development

Claude doesn’t waste time exploring different approaches. It goes straight to the correct implementation. What used to take multiple back-and-forth corrections now works on the first try.

Knowledge Preservation

Team decisions are encoded permanently. New developers learn from AI behavior. Your patterns self-document through consistent usage.

Quality Improvements

Anti-patterns get caught before they’re written. Error handling is consistent across the entire codebase. Proper separation of concerns is maintained automatically.

The Foundation for Advanced Automation

Once your CLAUDE.md files establish consistent patterns, they become the foundation for powerful automation:

Clear documentation = focused AI behavior
Focused behavior = reliable automation
Reliable automation = compound efficiency gains

AI stops guessing and starts following your patterns. Custom commands and specialized agents can build on your documented patterns with confidence.

Without this foundation, automation tools just amplify chaos. With it, they become force multipliers.

Get this documentation right first. Once your patterns are clear, custom Claude commands and agents become focused and reliable. Then you can start assembling workflows that actually work instead of fighting inconsistent AI behavior.

Key Takeaways

AI needs context to be effective - Generic AI gives generic results. Domain-specific training is essential.
Documentation as code - Must be maintained like code, lives with the code it documents, version controlled and reviewed.
Explicit > Implicit - Show exact patterns to follow, list specific anti-patterns to avoid, leave no room for interpretation.
Investment pays off - Time spent documenting saves multiples later. Consistency compounds value. Team knowledge becomes permanent.

Get Started: Example Prompts

For Rails Models: "Analyze my User and Post models and create a CLAUDE.md that enforces thin models with only validations, associations, and scopes. Business logic should go in service objects."

For Controllers: "Create a CLAUDE.md for my controllers directory that enforces: single responsibility actions, proper HTTP status codes, no business logic, and consistent error handling using rescue_from."

For Testing: "Generate a CLAUDE.md for my test directory that shows how to test behavior not implementation, avoid testing Rails itself, and use factories instead of fixtures."

For Service Objects: "Create a CLAUDE.md template for a service objects pattern where each service has a single public call method, returns Result objects, and handles its own errors."

Remember: Pragmatism Over Dogma

Pattern consistency matters more than pattern perfection. AI needs consistency more than SOLID principles. Pick patterns your team can understand and maintain.

Build in flexibility: - “Follow Command pattern EXCEPT when it adds no value” - “Use thin models UNLESS the alternative is worse”

AI mistakes will happen - make them easy to spot and correct.

Your First CLAUDE.md in 5 Minutes

Pick one directory (start with models)
Paste one of the prompts above
Review what Claude generates
Keep what works, fix what doesn’t
Save and test with a real implementation

The perfect documentation doesn’t exist. Good enough documentation that improves your workflow does.

What patterns are you struggling to keep consistent in your codebase?

Ready to take your CLAUDE.md files to the next level? Learn how to turn your best AI prompts into reusable commands that work with your patterns for even faster, more consistent development.

Vibe Coding Needs a Reality Check: Why AI-Generated Code Still Requires Engineering Discipline

2025-02-14T16:26:00+00:00

2025-02-14

Vibe Coding Needs a Reality Check: Why AI-Generated Code Still Requires Engineering Discipline

The term “vibe coding” has been making the rounds, painting a picture of a laid-back, intuitive way to write software with AI. The idea? You describe what you want, accept the AI-generated code, and move on. No stress, no deep dives, just code that vibes.

Except… the way that they make vibe coding sound is a setup for future problems.

Vibe Coding Isn’t New, Just Newly Branded

You, and many others, may have been working this way before the term “vibe coding” was popularized. AI-assisted development has been evolving for years, and developers have been using tools like Copilot, ChatGPT, and Claude to accelerate their work long before “vibe coding” became a buzzword.

The difference now? Marketing.

But just because AI can generate code faster doesn’t mean it’s automatically better. The reality is that AI-generated code needs oversight, structure, and engineering discipline, just like human-written code.

The Problem: Vibe Coding Sounds Too Passive

The phrase makes it sound like coding without guardrails, as if the AI is doing all the heavy lifting while developers sit back and let it happen. In reality, blindly accepting AI-generated code introduces major risks:

Maintainability Issues → AI doesn’t always optimize for long-term readability.
Performance Pitfalls → Code may work, but is it efficient at scale?
Security Vulnerabilities → AI doesn’t inherently understand security best practices.
Compounding Mistakes → Without oversight, one bad AI-generated decision can snowball into a bigger problem.

A Better Approach: Vibe Coding with Structure

If you’re going to use AI as part of your development process, you need a structured workflow that ensures quality and prevents long-term headaches.

Here’s what that should include:

✅ Code review checkpoints, with human-assisted review, at least for now.
✅ Testing and validation at every step, not just assuming AI-generated code is correct.
✅ Security checks built into the workflow to catch vulnerabilities early.
✅ **AI feedback loops to refine and improve suggestions over time.

AI is a tool, not a replacement for engineering judgment.

AI Coders Need Guardrails, or They Might Cause Damage

One of the biggest pitfalls of unrestricted vibe coding is that AI models degrade when built on top of previous AI-generated code.

If you accept AI-generated solutions blindly, without enforcing best practices, your assistant will accumulate hack upon hack. Eventually, the model performance will degrade, quality will drop, and it could start to reinforce its own mistakes.

A Slippery Analogy: Driving a Car vs. Fixing a Car

It’s true, you don’t need to be a mechanic to drive a car, but you need to know that you should not slam on the brakes when you hit ice.

You need to get to know the rules of the road for what you are vibing on.

Final Thoughts: Vibe Coding Isn’t Bad, But It Needs Discipline

AI-assisted development is here to stay, and vibe coding isn’t inherently a bad idea. But for it to work in the real world, it needs to be structured, tested, and reviewed.

✅ Use AI as a collaborator, not a crutch.
✅ Build processes to review, refine, and validate AI-generated code.
✅ Don’t let AI-generated shortcuts turn into long-term tech debt.

AI makes coding faster—but engineering discipline makes it sustainable.

What do you think? I know some people hate code generation, others love it.

UI Unblocker: A CustomGPT for Breaking Through UI Design Roadblocks

2025-02-14T02:22:00+00:00

2025-02-13

UI Unblocker: A CustomGPT for Breaking Through UI Design Roadblocks

Sometimes, a UI just doesn’t feel right. You tweak layouts, adjust spacing, change colors, but something is still off. That’s when I started using AI as a UX auditor—not to replace design tools, but to help me break through creative blocks.

I put together UI Unblocker, a CustomGPT designed for one-off UI brainstorming tasks. It’s not a replacement for an expert, or Figma, Uizard, or any full-fledged design system. It’s just a quick way to get fresh ideas when refactoring an interface or structuring new information architecture, especially for people like me that work across a whole stack.

Why UI Design Gets Stuck

UI design is more than just visuals—it’s about usability, flow, and user expectations. When working on a product, it’s easy to lose perspective and fall into familiar patterns. Sometimes you just need a little nudge to get things into a better position.

That’s where UI Unblocker comes in. It’s a fast way to analyze, critique, and suggest improvements to what’s already there.

How UI Unblocker Works

I use it in a simple workflow:

Take a screenshot or describe the UI in text.
Explain the screen’s intent (e.g., “This is a pricing page, but I feel like it’s not clear enough”).
Ask UI Unblocker to analyze it based on modern UX best practices.
If I need more ideas, I request visual concepts.
Iterate until I have a clear direction.
Run a final check through UI Unblocker to make sure nothing regressed.

If I had to do this at scale, I’d use a dedicated tool, but for occasional use, this process works well.

Prompts – Tweak as Needed

There are two prompts at the end of this article

The first is the CustomGPT instruction set used in UI Unblocker
The second is a version that can be used as a regular prompt to copy and paste

When to Use UI Unblocker vs. Other Tools

✅ UI Unblocker → When you’re stuck and need quick, fresh input.
✅ AI UX Auditors (like Uizard, Galileo AI) → When you need usability scores and structured feedback.
✅ Figma/Sketch → When iterating on and finalizing a full design.

AI as a UX Assistant, Not a Designer

The goal isn’t to replace UX designers or design tools. It’s to get unstuck faster when working through UI issues. Sometimes, all you need is a fresh perspective to see what’s been in front of you the whole time.

If you use the prompt, I’d be interested to hear how you tweak it.

Prompt

### Custom GPT Instructions

💡 **You are an AI UX and UI design expert.** Your role is to generate **functional, structured UI mockups** while ensuring **best UX practices**.

🎯 **Your Goal:**  
- Provide a **clear, structured wireframe representation** of a UI layout.  
- **No colors, shadows, artistic styling, or abstract embellishments.**  
- Focus on **information hierarchy, spacing, and layout clarity**.  
- Optimize outputs for **developer-friendly implementation**.  

---

## 🔹 **1️⃣ Analyze the User's Intent**  
   - If the user is **creating a new UI**, ask for structured input:
     ✅ **What is the UI’s purpose?**  
     ✅ **Who is the target audience?**  
     ✅ **What are the key actions users should take?**  

   - If the user provides a **screenshot**, analyze and extract:  
     ✅ **Only the layout, structure, and key UX elements**  
     ✅ **Ignore colors, branding, and artistic elements**  
     ✅ **Identify repeating patterns and component structures**  

---

## 🔹 **2️⃣ Build a Structured UI Table + JSON Wireframe**  
✅ **Step 2a: Generate a human-readable table** summarizing all UI elements.  
✅ **Step 2b: Convert the table into a JSON-based wireframe structure.**  

   - The **table helps the user quickly scan and confirm information**.  
   - The **JSON wireframe provides structured input for UI generation**.  

✅ **Step 2c: Define Consistent Structure for Repeating Sections**  
   - If the UI includes **repeated content elements** (e.g., albums, products, articles), **use a structured template** rather than defining each item individually.  
   - Define repeating sections as **data-driven components** for flexible updates.  

   **Structure Guidelines:**  
   - **Lists:** Use consistent spacing, typography, and metadata placement.  
   - **Grids:** Ensure uniform card sizes and clear gutters.  
   - **Dynamic Sections:** Paginate or provide scrolling mechanisms as needed.  

   **Example JSON for a repeating section:**
   ```json
   {
      "trending_albums": {
         "grid_layout": "4-column",
         "cards": [
            {
               "album_cover": "placeholder.svg",
               "album_title": "Example Album",
               "artist_name": "Artist Name",
               "track_count": "8 Tracks"
            },
            {
               "album_cover": "placeholder.svg",
               "album_title": "Another Album",
               "artist_name": "Different Artist",
               "track_count": "12 Tracks"
            }
         ]
      }
   }

## 🔹 3️⃣ Provide UX Recommendations + User Confirmation
- Evaluate **usability, accessibility, clarity, and interaction design**.
- Suggest **layout improvements** (e.g., readability, padding, navigation refinement).
- Display recommendations in an **easy-to-read format** before generating UI.
- Allow users to **approve or modify recommendations** before proceeding.

---

## 🔹 4️⃣ Generate Two Simple UI Mockups from the Wireframe  
✅ **Step 4a: HTML + Tailwind CSS Mockup**  
- Generate a **structured UI using HTML & Tailwind CSS**.  
- **No need for functional interactivity**—only layout and structure.  
- **Use SVG or CSS placeholders** where content images would be.  

✅ **Step 4b: Image-Based Wireframe Rendering**  
- Generate a **minimal grayscale UI wireframe image** from the JSON wireframe.  
- **No unnecessary artistic details—only layout clarity**.  
- **Only generate an image upon request** to optimize chat interactions.  

---

## 🔹 5️⃣ Iterate Based on User Feedback  
- Allow the user to **accept, modify, or request alternative designs**.  
- If needed, generate **simplified variations** (e.g., **list vs. grid, compact vs. spacious layouts**).  
- Ensure **developer-friendly outputs** that can be easily implemented.  

---

## 🔍 **If the user asks for UX improvements, prioritize:**  
✅ **Navigation efficiency** (reduce clicks, intuitive placement).  
✅ **Readability** (proper text hierarchy, no clutter).  
✅ **Action clarity** (buttons & CTAs stand out).  
✅ **Accessibility compliance** (keyboard navigation, minimal cognitive load).  

💡 **All UI mockups must be structured, minimal, and strictly wireframe-based. NO unnecessary decorations, branding, or visual effects.**

P.S. If you prefer to use this as a regular prompt to copy and paste, or inject into some other workflow, here is a version for that:

You are an AI UX and UI design expert. Your task is to generate **functional, structured UI mockups** while ensuring **best UX practices**. Follow the instructions below with careful.

🎯 **Your Goal:**  
- Provide a **clear, structured wireframe representation** of a UI layout.  
- **No colors, shadows, artistic styling, or abstract embellishments.**  
- Focus on **information hierarchy, spacing, and layout clarity**.  

---

🔹 **1️⃣ Analyze the User's Intent**  
   - If the user is creating a new UI, **gather structured input** about its purpose, audience, and key actions.  
   - If they provide a screenshot, extract **only** its **layout, structure, and key UX elements** (ignore colors or artistic styles).  

---

🔹 **2️⃣ Build a Structured UI Table + JSON Wireframe**  
   ✅ **Step 2a: Generate a human-readable table** summarizing all UI details.  

   ✅ **Step 2b: Convert the table into a JSON-based wireframe structure.**  
   - The **table helps the user quickly scan and confirm information** before proceeding.  
   - The **JSON wireframe serves as the structured input for generating the mockup.**

   ✅ **Step 2c: Define Consistent Structure for Repeating Sections**  
      - If the UI includes **repeated content elements** (e.g., albums, products, articles), **use a structured template** rather than defining each item individually.  
      - Define repeating sections as **data-driven components** in both JSON and HTML to allow for flexible updates.  
      - **Structure guidelines:**  
      - **Lists:** Use consistent spacing, typography, and metadata placement.  
      - **Grids:** Ensure uniform card sizes and clear gutters.  
      - **Dynamic Sections:** Paginate or provide scrolling mechanisms as needed.  
      - Example JSON for a repeating section:
      ```json
      {
      "trending_albums": {
         "grid_layout": "4-column",
         "cards": [
            {
            "album_cover": "placeholder.svg",
            "album_title": "Example Album",
            "artist_name": "Artist Name",
            "track_count": "8 Tracks"
            },
            {
            "album_cover": "placeholder.svg",
            "album_title": "Another Album",
            "artist_name": "Different Artist",
            "track_count": "12 Tracks"
            }
         ]
      }
      }   

---

🔹 **3️⃣ Provide UX Recommendations + User Confirmation**  
   - Evaluate **usability, accessibility, clarity, and interaction design**.  
   - Suggest **layout improvements, readability enhancements, and navigation refinements**.  
   - **Display these recommendations in an easy-to-read format** for user approval.  
   - **Before proceeding, ask the user to confirm or modify** the recommendations.  

---

🔹 **4️⃣ Generate Two Simple UI Mockups from the Wireframe**  
   ✅ **Step 4a: HTML + Tailwind CSS Mockup**  
   - Generate a simple, structured UI using **HTML & Tailwind CSS**.  
   - **No need for functional interactivity**—just the visual structure.  
   - **Use SVG or CSS placeholders** where content images would be.  

   ✅ **Step 4b: Image-Based Wireframe Rendering**  
   - Generate a **minimal grayscale UI wireframe image** from the JSON wireframe.  
   - **No unnecessary artistic details**—only layout clarity.  

---

🔹 **5️⃣ Iterate Based on User Feedback**  
   - Allow the user to **accept, modify, or request alternative designs**.  
   - If needed, generate **simplified variations** (e.g., **list vs. grid, compact vs. spacious layouts**).  

---

🔍 **If the user asks for UX improvements, prioritize:**  
✅ **Navigation efficiency** (fewer clicks, intuitive placement of elements).  
✅ **Readability** (proper spacing, minimal text overload).  
✅ **Action clarity** (CTAs must stand out, key actions easy to complete).  
✅ **Accessibility compliance** (keyboard navigation, minimal cognitive load).  

💡 **All UI mockups must be structured, minimal, and strictly wireframe-based. NO unnecessary decorations, branding, or visual effects.**  

---

### **🚀 Next Steps**
Would you like me to **test this refined workflow now** by generating a UI mockup **from scratch** or using your provided screenshot? 🚀 Let me know how you'd like to proceed!

🤖 Refactoring GraphQL with AI Coding Assistants: A Real-World Use Case

2025-02-09T20:08:00+00:00

2025-02-09

🤖 Refactoring GraphQL with AI Coding Assistants: A Real-World Use Case

AI coding assistants are everywhere, but much of the content focuses on simplistic, contrived demos. “Hey AI, make me a to-do list app!” Of course, greenfield projects work like magic. The real test is applying AI to large, messy, real-world codebases that have evolved over time. That’s what I did while refactoring a legacy GraphQL API to support a new database schema without breaking the public interface.

This is how AI coding assistants work in practice: useful, but not magic. Here’s how I structured the process to make them work effectively.

The Challenge: Schema Fixes Without Breaking the Frontend

The goal was to fix deficiencies in an existing survey system schema that were holding back progress. But there was a catch: the frontend React developers couldn’t be derailed from their existing work. That meant preserving the GraphQL API interface while completely restructuring the underlying schema.

On top of that, the codebase was old, large, and undocumented, built by a previous team with inconsistent standards. No easy wins here.

Step 1: Define the Ideal Schema

Before touching any code, I manually designed the ideal schema based on current and future needs. This set a clear target for all changes.

Step 2: AI-Assisted Implementation Planning

A coding assistant (Claude 3.5 Sonnet via Cursor) was given a structured prompt outlining:

The current and future state of the schema
The need to maintain API compatibility
The backend services impacted

It produced an initial high-level implementation plan, which I iterated on. AI won’t always get this perfect on the first try, but it accelerates structured thinking.

Step 3: Implement & Validate the New Schema

Once we had a vetted plan, I manually implemented the new schema in isolation, ensuring:

Built the new database objects (ActiveRecord objects in this case)
Validated attributes and relationships
Implemented queries and data validation
Wrote unit tests

Now came the detailed part: mapping the new schema without breaking anything.

Step 4: AI-Driven Query Mapping

Since the frontend relied on GraphQL queries that referenced the old schema, I used an AI-assisted pipeline to:

Scan the React app to locate every GraphQL query touching the affected schema fields.
Extract query parameters and store them in a structured “plan file.”

This created a map of dependencies, ensuring nothing slipped through the cracks.

Step 5: AI-Guided Backend Refactoring

With the plan file in place, I tasked the AI assistant with analyzing the Rails GraphQL API:

Identifying where each GraphQL query was defined
Mapping which GraphQL types were impacted
Generating an implementation plan for incrementally updating queries to match the new schema

Step 6: Fine-Tuning the Migration Plan

Before running anything, I added manual replacement rules to the plan file:

Direct class and attribute name swaps (e.g., Apple -> Orange)
Schema transformations (where more complex rewrites were needed)
Example snippets for AI-generated suggestions

Step 7: AI-Assisted Code & Test Generation

I fed the refined plan into Cursor (Claude 3.5 Sonnet) and tasked it with:

Refactoring GraphQL query resolvers incrementally.
Writing missing tests (huge testing gaps existed in the original implementation).

AI excelled at scaffolding tests and reducing code-hunting time, but was less reliable in fully rewriting complex query logic. Still, the time saved on searching through a massive codebase made it worth it.

The Results: A Hybrid AI/Human Approach

By combining AI-powered dependency mapping, automated planning, and test generation with manual architecture and validation, I successfully:

✅ Migrated the GraphQL API to a new schema without frontend disruption.
✅ Used AI to eliminate hours of code searching and documentation gaps.
✅ Applied targeted refactoring instead of risky full rewrites.

Final Takeaways

1️⃣ AI isn’t a magic bullet, but it’s a fantastic tool for structuring large-scale refactors.
2️⃣ Manual oversight is still critical—especially in high-stakes migrations.
3️⃣ AI is best used for accelerating repetitive tasks: scanning, planning, scaffolding tests.

🔹 Have you used AI for refactoring in real-world projects? How did it go?

Getting AI Coding Assistants From OK To Great

2025-01-10T02:43:00+00:00

2025-01-09

Getting AI Coding Assistants From OK To Great ⚙

I’ve been experimenting with AI coding tools to see if I could improve their effectiveness. My focus has been on training Cursor AI for a specific project I’m working on at RiseKit.

Here’s what I done so far:

✅ Rules and Templates

I created a rules file with project-specific coding standards, architecture patterns, testing guidelines, and documentation requirements.

💬 Pre-composed Prompts

These covered common tasks like code reviews, test writing, and generating documentation.

🔁 Stateful Prompts

For more complex, multi-step tasks, I built prompts that maintain context across sessions, ensuring consistency in longer operations.

The AI Composer updates the stateful prompt as the task progresses, sometimes with my direction, othertimes it will prompt me to confirm when a step appears complete.

🛠️ How I built the rules and templates

One of the most useful aspects was using AI itself to refine these rules and templates.

I started with a short paragraph of instructions on a topic, like coding standards, documenation, testing or implementation planning, and would ask the AI expand on the concept and come up with an AI optimized version of the rules.

I then iterated on a rule file. That involved some editing by myself and also asking the AI to analyze and improve the rules.

If the rules had to do with coding, I would ask it repeadly to analyze the code base for certain patterns regarding specific layers of the codebase like views, controllers, models, business rules, etc. If sensible patterns were missing, I would introduce one based on best practices. Coding examples are paired with the rules.

Don’t be shy with the instructions you give to the AI, you won’t frighten it or bore it to death. You’ll be turning it into a domain expert for your project and ideals.

This approach has worked well for a few established codebases. Refactoring becomes easier, and the AI performs better as the codebase becomes cleaner and more consistent.

Good code quality and documentation are just as important with AI tools as without, they rely on clear patterns to function effectively.

If the codebase is messy, the AI can get off track or produce a lot more inaccurate suggestions. But when you invest in training the tools and maintaining code quality, you create a positive feedback loop: each improvement makes the AI faster and more accurate.

AI coding assistants are not a replacement for good practices—they are a way to enhance them.

Process Spawning with Ruby

2023-10-01T00:43:00+00:00

2023-09-30

Process Spawning with Ruby ⚙

In 2015, I needed a way to record audio streams on a scheduled basis. To accomplish this I created a Rails app called Radioshifter that served as a UI for editing and storing schedules. Under the hood, Radioshifter did a lot of things. One of those things was spawning new processes whenever it was time to capture an audio stream.

Radioshifter - R.I.P. 🪦☠

Methods

There are a few ways to spawn a process with Ruby - system, fork, exec, Process.spawn, and loads more options in Open3 and PTY. Each method has its own use case.

The Method I Chose

I chose Process.spawn because there was no need to wait for the process to finish. I just needed the code to spawn a new process, then detach from the current process with Process.detach, and let the current process finish while the spawned process continued to run.

The Spawned Process

To give you some context, the spawned process was responsible for recording an audio stream. It orchestrated the recording process by calling serveral other system level commands. Some later stage processes even observed other processes, ending them at specific times, or restarting them if they crashed prematurely.

The spawned process was the starting point for a chain of events that involved the following:

capturing the audio stream to disk using mplayer
converting the audio file(s) to an MP3 file using ffmpeg
uploading the MP3 to a user’s Dropbox account
cleaning up local recording files

Caveats

While some of the priciples still hold true, the application was made in 2015 and my approach might be a bit different today.

I also would probably name the classes a bit differently now. I’m not a huge fan of the -er -or naming convention that I used for certain classes, but I digress!

The Code

Here is the starting point:

module Scheduler
  class RecordingProcess
    attr_reader :recording_schedule

    def initialize(recording_schedule)
      @recording_schedule = recording_schedule
      @pid_file_name = @recording_schedule.pid_file_name
    end

    def spawn
      return if running?
      logfile_path_option = if ENV['RECORDINGS_LOG_FOLDER']
        "-l #{ENV['RECORDINGS_LOG_FOLDER']}/#{recording_schedule.id}/recording.log"
      end

      pid_file_option = "-p #{@pid_file_name}"

      command = "cd #{Rails.root}/bin && FFMPEG_CMD=#{ ENV['FFMPEG_CMD'] } FFPROBE_CMD=#{ ENV['FFPROBE_CMD'] } ./record_stream -i #{ @recording_schedule.id } -u #{ @recording_schedule.stream_url } -d #{ @recording_schedule.duration } -f /tmp/radio_shifter_recording/#{ @recording_schedule.id } #{logfile_path_option} #{pid_file_option} > /dev/null"
      pid = Process.spawn(command)
      Process.detach(pid)
    end

    # TODO - Stop using PID to prevent duplicate recordings.
    # Have the recorder get a fail lock and exit on fail
    # We still want the PID for other reasons, so have the recorder
    # send it's PID to message queue when it starts, and wipe the PID
    # when it stops.
    def running?
      if File.exists?(@pid_file_name)
        pid = File.read(@pid_file_name).strip.to_i
        begin
          Process.kill(0, pid) == 1
        rescue Errno::ESRCH
          false
        end
      else
        false
      end
    end
  end
end

#!/usr/bin/env ruby
require 'logger'
require 'backburner'
require 'stalker'
require 'optparse'
require 'etc'
require 'fileutils'

class Rails
  class EnvString < String
    def development?
      self == 'development'
    end

    def production?
      self == 'production'
    end

    def test?
      self == 'test'
    end
  end

  def self.env
    @env ||= EnvString.new(ENV["RAILS_ENV"] || 'development')
  end
end

require_relative '../app/extras/services/recording_uploader'
require_relative '../config/initializers/backburner'
require_relative '../lib/scheduler/audio_concatenator'
require_relative '../lib/scheduler/audio_prober'
require_relative '../lib/scheduler/command_line_error'
require_relative '../lib/scheduler/mp3_audio_converter'
require_relative '../lib/scheduler/recorder'
require_relative '../lib/scheduler/recording_process_manager'
require_relative '../lib/scheduler/wav_audio_converter'

ENV['FFMPEG_CMD'] ||= 'ffmpeg'
ENV['FFPROBE_CMD'] ||= 'ffprobe'

# TODO - Research changing the process user and group.
#        This doesn't seem to work on Ubunto.
if Rails.env.production?
  u = Etc.getpwnam('rails')
  Process.uid = u.uid
  Process.gid = u.gid
end

options = {}
OptionParser.new do |opts|
  opts.banner = "Usage: record_stream [options]"
  opts.on('-i', '--schedule_id SCHEDULE_ID', 'The Schedule ID this recording belongs to') { |v| options[:schedule_id] = v }
  opts.on('-u', '--url URL', 'url to record from') { |v| options[:url] = v }
  opts.on('-d', '--duration SECONDS', 'Number of seconds to record') { |v| options[:duration] = v.to_i }
  opts.on('-f', '--folder FOLDER', 'The folder to place the recording in') { |v| options[:folder] = v }
  opts.on('-l', '--logfile FILE', 'The log file ') { |v| options[:log_file] = v }
  opts.on('-p', '--pidfile FILE', 'The PID file ') { |v| options[:pid_file] = v }

end.parse!

Process.daemon

logger = if options[:log_file]
  File.truncate(options[:log_file], 0) if File.exists?(options[:log_file])
  FileUtils::mkdir_p File.dirname(options[:log_file])
  Logger.new(options[:log_file])
end

recorder = Scheduler::Recorder.new(
  options[:url],
  options[:duration],
  options[:folder]
)

FileUtils::mkdir_p options[:folder]
FileUtils::mkdir_p File.dirname(options[:pid_file])
# TODO This is a stop gap for the above process permission issue.
if ENV["RAILS_ENV"] == 'production'
  FileUtils.chown 'rails', 'www-data', options[:folder]
  FileUtils.chown 'rails', 'www-data', File.dirname(options[:pid_file])
end

# TODO This is a stop gap for the above process permission issue
File.open(options[:pid_file], 'w') {|f| f.write(Process.pid) }
if ENV["RAILS_ENV"] == 'production'
  FileUtils.chown 'rails', 'www-data', options[:pid_file]
end

recording_manager = Scheduler::RecordingProcessManager.new(
    options[:schedule_id],
    recorder,
    ENV['FFMPEG_CMD'],
    ENV['FFPROBE_CMD'],
    logger
  )

recording_manager.start
logger.close

if File.exists?(options[:pid_file])
  File.delete(options[:pid_file])
end

module Scheduler
  class RecordingProcessManager
    def initialize(schedule_id, recorder, ffmpeg_path, ffprobe_path, logger = nil)
      @schedule_id = schedule_id
      @recorder = recorder
      @ffmpeg_path = ffmpeg_path
      @ffprobe_path = ffprobe_path
      @logger = logger
    end

    def start
      begin
        run
      rescue CommandLineError => e
      rescue CommandLineError => e
        if @logger
          @logger.error "Command line error."
          @logger.error "#{e.message}"
          @logger.error "#{e.command_output}"
          @logger.error e.backtrace.join("\n")
        end
      rescue Exception => e
        if @logger
          @logger.error "#{e.message}"
          @logger.error e.backtrace.join("\n")
        end
      end
    end

    def run
      success = false
      @recorder.start
      sleep 5
      # TODO - put the following steps into a separate
      # async action
      wav_converter = Scheduler::WavAudioConverter.new(@ffmpeg_path, @recorder.dump_files)
      wav_files = wav_converter.convert
      finalized_wav_file = get_finalized_wav_file(wav_files)
      if finalized_wav_file
        mp3_bitrate = wave_bitrate_to_mp3_bitrate(
          Scheduler::AudioProber.new(@ffprobe_path, finalized_wav_file, @logger).bitrate
        )
        mp3_file = finalized_wav_file.gsub('.wav', '.mp3')
        mp3_converter = Scheduler::Mp3AudioConverter.new(@ffmpeg_path, finalized_wav_file, mp3_file, mp3_bitrate, @logger)
        if mp3_converter.convert
          Services::RecordingUploader.async.upload(@schedule_id, mp3_file)
          cleanup_recording_folder(@recorder.folder)
          success = true
        end
      end
      success
    end

    private

    def cleanup_recording_folder(folder)
      files = Dir[folder + '/*.*'].select{|f| !File.directory?(f) &&  File.extname(f) != '.mp3' }
      File.delete(*files)
    end

    def get_finalized_wav_file(wav_files)
      if wav_files.size > 1
        output_file = "#{@recorder.folder}/combined.wav"
        concatenator = Scheduler::AudioConcatenator.new(@ffmpeg_path, wav_files, output_file)
        return output_file if concatenator.concatenate
      else
        wav_files.first
      end
    end

    def wave_bitrate_to_mp3_bitrate(wav_bitrate)
      if wav_bitrate <= 500000
        '48k'
      elsif wav_bitrate <= 800000
        '64k'
      elsif wav_bitrate <= 1199999
        '96k'
      else
        '128k'
      end
    end

  end
end

Conclusion

When spawning a new process with Ruby, the method you choose will depend on your use case. In my case, I needed to spawn a new process and detach from the current process. In other cases someone might want to wait for the spawned process to finish. Then there are times you way want to read the process output as it happens, and even send it input while it’s running. I hope this article was is helpful in deciding which method to use when spawning a new process with Ruby.

Inter-Process Communication With Ruby

2023-08-29T02:31:00+00:00

2023-08-28

Inter-Process Communication With Ruby 🔄

In 2015, I needed a way to record audio streams on a scheduled basis. To accomplish this, I created a Rails app called Radioshifter that served as a UI for editing and storing schedules. In a separate process, a rufus-scheduler would run and start/stop various command line applications that captured online audio streams to disk and uploaded them to Dropbox.

Radioshifter - R.I.P. 🪦☠

Choosing a Method for Interprocess Communication

I looked at various methods for interprocess communication with Ruby, which included:

pipes
shared memory
message queues
sockets
RPC frameworks
Ruby dRb

dRb: The Right Tool for the Job

I ultimately chose dRb (distributed Ruby) for its simplicity and ease of use.

The dRb fronted process didn’t have too much to worry about in terms of processing messages. All it needed to do was take a message and edit rufus-scheduler’s job list. dRb seemed capable enough for that type of message load.

To enable communication between the Rails app and the scheduler, I used dRb. dRb is a distributed object system for Ruby. It allows you to expose objects to other processes and communicate with them. dRb is a part of the Ruby standard library, so it’s available out of the box. There are two main components to a dRb implementation, whatever you choose to be the server, and a client or clients.

My dRb Implementation in Radioshifter

Things to keep in mind:

I did this in 2015, so some of the code may be a bit dated.
I did this in a hurry, so there are some things that could be improved.
At this point in time, there are probably better ways to do this
There’s no built in or durability or retrying with dRb, like a robust message queue would have.
I’ve never looked into the performace limits of dRb.

With that being said, there is a time and place for dRb, and it’s a good tool know about.

Below are the critical entry points for the dRb implementation, but you can also view the full application source code on the repository. I’m also no longer really fond of the -er -or naming convention that I used for certain classes, but I digress!

# The executable that starts the scheduler which is fronted by dRb

#!/usr/bin/env ruby
require 'drb'
require File.expand_path('../../config/environment', __FILE__)

ENV['RAILS_ENV'] ||= 'development'
ENV['RUFUS_SCHEDULER_SERVER_PORT'] ||= '9000'
ENV['RECORDINGS_LOG_FOLDER'] ||= File.expand_path('../../log/recordings', __FILE__)

trap("INT") { exit }

RUFUS_SCHEDULER = Rufus::Scheduler.new

server = Scheduler::Server.new(RUFUS_SCHEDULER)
bootstrapper = Scheduler::ServerBootstrapper.new(server, RecordingSchedule)
bootstrapper.bootstrap

DRb.start_service("druby://localhost:#{ENV['RUFUS_SCHEDULER_SERVER_PORT']}",
  server
)
DRb.thread.join

# The server class that exposes the scheduler

module Scheduler
  class Server
    include ::Scheduler::JobTransformations

    def initialize(scheduler)
      @scheduler = scheduler
      @job_editor = Scheduler::JobEditor.new(@scheduler)
      @lock = Mutex.new
    end

    def cron(recording_schedule)
      @lock.synchronize do
        @job_editor.cron(recording_schedule)
      end
    end

    def at(recording_schedule)
      @lock.synchronize do
        @job_editor.at(recording_schedule)
      end
    end

    def unschedule(job_id)
      @lock.synchronize do
        @job_editor.unschedule(job_id)
      end
    end

    def job(job_id)
      begin
        job = @scheduler.job(job_id)
        job_to_hash(job) if job
      rescue ArgumentError => e
        nil
      end
    end

    def jobs(job_ids)
      found_jobs = job_ids.map do |id|
        job(id)
      end

      found_jobs.compact
    end
  end
end

# The dRb client initializer.
# In my app this is located at: config/initializers/rufus-scheduler.rb

require 'drb'
RUFUS_SCHEDULER_CLIENT = DRbObject.new(nil, 'druby://localhost:9000')

# Note: this must be called at least once per process to take any effect.
# This is particularly important if your application forks.
DRb.start_service

# Calling the dRb Client.

class RecordingSchedulesController < ApplicationController
  before_action :authenticate_user!
  before_action :redirect_to_time_zone, if: Proc.new { current_user.time_zone.blank? }

  def index
    @recording_schedules = RecordingSchedule.where(user_id: current_user.id).order(:name).decorate
  end

  def new
    @recording_schedule = RecordingSchedule.new
  end

  def create
    @recording_schedule = RecordingSchedule.new(recording_schedule_params).decorate
    @recording_schedule.user = current_user
    notifier = Services::ScheduleNotifier.new(@recording_schedule, RUFUS_SCHEDULER_CLIENT)

    if notifier.save
      redirect_to recording_schedules_path, flash: { success: 'Recording schedule added.' }
    else
      flash.now[:error] = "There were some problems with this recording schedule."
      render :new
    end
  end

  def destroy
    @recording_schedule = RecordingSchedule.find(params[:id]).decorate
    notifier = Services::ScheduleNotifier.new(@recording_schedule, RUFUS_SCHEDULER_CLIENT)
    flash_options = {}

    if notifier.destroy
      flash_options[:success] = 'Recording schedule removed.'
    else
      flash_options[:success] = 'Recording schedule not removed.'
    end

    redirect_to recording_schedules_path, flash_options
  end

  def edit
    @recording_schedule = RecordingSchedule.where(id: params[:id], user_id: current_user.id).first
  end

  def update
    @recording_schedule = RecordingSchedule.where(id: params[:id], user_id: current_user.id)
      .first
      .decorate
    notifier = Services::ScheduleNotifier.new(@recording_schedule, RUFUS_SCHEDULER_CLIENT)

    if notifier.save(recording_schedule_params)
      redirect_to recording_schedules_path, flash: { success: 'Changes saved.' }
    else
      flash.now[:error] = "There were some problems with this recording schedule."
      render :edit
    end
  end

  private

  def recording_schedule_params
    strip_blank_from_days_of_week(
      params
        .require(:recording_schedule)
        .permit(:duration, :stop_time, :name, :recurring,
         :start_on, :start_time, :stream_url, days_of_week: []
        )
    )
  end

  def redirect_to_time_zone
    redirect_to time_zone_path
  end

  def strip_blank_from_days_of_week(permittied_params)
    if permittied_params[:days_of_week].present?
      permittied_params[:days_of_week]
        .reject! {|i|i.blank?}
        .collect!(&:to_i)
    end
    permittied_params
  end
end

Conclusion

Overall, using dRb for interprocess communication in Ruby proved to be a reliable and efficient solution for my audio recording system. While there are other methods available for interprocess communication in Ruby, dRb’s simplicity and ease of use made it a good choice for my use case.

Building a Hot Tub from Scratch

2023-08-25T02:10:00+00:00

2023-08-24

Building a Hot Tub from Scratch 🛀

I went to Iceland a while back, which was fantastic. During my time there, I enjoyed a daily soak in a hot tub. After a few days of soaking I noticed a lot of nagging aches and pains were gone. So I thought, damn, I need to get one of these for my house some day. I would shop around, but never pull the trigger. Finally, in 2019, I made the decision to pursue this.

I wanted a big round, 4 feet deep cedar hot tub. Now, since this was a pretty expensive purchase, and I didn’t want to be compulsive, I figured I would budget the purchase. January 2020 rolled around, I was ready to buy, but caught up on which cedar tub manufacturer to buy from, and I had it down to three. Then February 2020 came, the COVID-19 shut down, and everyone bought every hot-tub, all at once, and there was an 18 - 24 month wait …but I wanted a hot tub sooner than that.

That’s when the idea of building one struck me. How hard could it be? So I got to work around October 2020.

I originally intended to base the hot tub off of a prefabricated water tank, but due to supply chain issues, I could not get a tank in appropriate dimensions, so I went with a custom built wood basin with a custom liner. The hot tub related forums had a lot of mis-information on them about what you can and can’t build a basin out of, so I looked into aquafarmer and back-yard fish enthusiast communities, and picked one of their designs.

I bought hot tub parts, which are the controller, heater, filter, and other related items from buildahottub.com, Andi over there knows everything about these systems.

The basic specs are:

Above ground design
A base framed with pressure treated timbers and filled in with 0.75 inch packed stone.
Walls built with standard construction boards, filled with insulation, and lined with plywood and siding.
Industrial pond liner, custom made, in a box shape
All necessary of hot tub heaters and controllers
Plumbing pipe, hoses, connectors
A standard hot tub cover

Problem 1 - City Permitting

The first wrinkle was the city permitting. I started this process in September of 2020. We are allowed to have hot tubs, but I needed an electrical service upgrade on the house to accommodate a hot tub. It took the city about 6 months to sign off, which threw some dependencies off course. I only interacted with them a little, I didn’t get the sense they excelled at customer service and I’m totally fine not having to work with them again. I later learned after speaking to area trades people, that a significant number of electricians will not take work in my city.

Problem 2 - Changing the Construction Location

By now it was October. I originally planned to build the hot tub in the place that was to be used, but since the city was doing what they do best, and the weather was turning, I decided to start the work on the basin inside. As the weather turned, I opted to begin work on the basin indoors. This required constructing the basin in a way that it could be disassembled and reassembled in its final location.

Electrical Work Approved ⚡

It was now March 2021. The city finally agreed the electric work could start. The delay was over the location of the electric meters, which usually go outside of the house, but they are inside of ours, for a good reason. We live in a dense area, and there is no other location they could be at other than the front of the house, or inside of the basement. They were insisting they had to be relocated outside of the house. They didn’t want the electric meters in the front of the house because they would block the sidewalk, but the sidewalk is 10 feet away. Then they suggested the driveway, but the driveway is between two buildings and narrow. A vehicle would have hit the meters. They can’t go behind the house, because of other obstructions. It took several meetings, and input from both the electrician and the utility company for reality to set in, which means the meters are staying where they are.

Problem 3 - Less Than Ideal Basin Liner

I chose an industrial pond liner because at the time, it was the only one I could find that could be custom made into a box shape. Had I known a bit more about what to look for, I could have gotten a box shaped pool liner made. Both types of liners are durable and will hold water, but the pond liner isn’t compatible with the seals on the through-wall fittings. The through-wall fittings are the plumbing parts that circulate the water between the basin, filter and heater.

So after a lot of leaks, I had to come up my own through wall design for this type of tub. On top of that, I also had to remove the hot-tub jets and replace them with a jet-like construct that I made out of standard plumbing parts so I could get those to seal correctly.

Problem 4 - Unexpected mistakes

I don’t think many people have built a hot-tub like this, and since this was my first try, I made mistakes. One of them was making some cuts on the liner. To repair them, I had to learn how to heat-weld.

Conclusion

Today, I have a fully functioning hot tub that holds water, along with some plumbing skills that I’ve had to use a few times since then.

Internationalization with Ruby on Rails with I18n

2023-08-21T15:43:00+00:00

2023-08-21

Internationalization with Ruby on Rails with I18n

Internationalization is the process of designing and developing web applications that can support multiple languages and locales. This is an important consideration for any web application that needs to reach a global audience, as it allows users to interact with the application in their preferred language and format.

Ruby on Rails provides built-in support for I18n, making it easy to create and manage translations for different languages. The humanization helpers of ActiveRecord and ActiveModel I18n, and you can leverage this to make you application support multiple languages, and to also humanize your object names and attributes to generate human readable content and forms.

Take the following two example screens from www.cboflow.com, a Rails application that I maintain. The first is in English, and the second is in Spanish. Using the strategies outlined in this article, I was able to make this application support multiple languages with minimal effort.

English Screen

Spanish Screen

I18n and Rails

A new Rails application is configured to use I18n by default.

All of the translations are stored in resource files within the project's config/locales directory. Each file has to end with a language code, and .yml. So for example, you might have a file named config/locales/en.yml, with the following content:

  
      en:
        hello: "Hello, world!"

In this folder, you can have as many subfolder as you like, and prefix the files as you wish. Some people like to have one large locale file for each supported language, while others like to have one file per object or view. For example, keeping all content in config/locales/en.yml, or breaking the content up into several files like config/locales/author.yml and config/locales/post.yml

The Rails Guide has a lot of information about using this feature.

How I use I18n in my own Rails applications

I try to use the same lingo across my applcations.

I will create one locale file for each object that I intent to humanize in a view.

So if I have a Person model, I'll have a person.en.yml file, and more files for other languages like peroson.es.yml.

The default humanization for an attribute name is the same as String#humanize, so Person#first_name will become First name be default, and if I am happy with that, I probably will not make a translation entry.

I also tend to use gems like simple_form to generate my form HTML, and this saves me from having to maintain a lot of view code for outputting translated content onto forms. Also simple_form has it's own i18n convention that compliments the Rails default pretty well.

  
  # person.en.yml
  en:
    activerecord:
      models:
        person:
          one: Person
          other: People
    attributes:
      person/hispanic:
        true: 'Yes'
        false: 'No'               
      errors:
        models:
          person:
            attributes:
              birth_date:
                must_be_in_the_past: "can't be before today"
                must_be_formatted_correctly: "must be formatted like yyyy-mm-dd"
              full_name:
                blank: "can't be blank"
              email:
                invalid: "is not valid. It should look like name@domain.com"
              phone_number:
                invalid: "is not valid. It should look like 123-456-7890"

  
  # person.es.yml
  es:
    activerecord:
      models:
        person:
          one: "Persona"
          other: "Personas"
      attributes:
        person:
          birth_date: "Fecha de nacimiento"
          email: "Correo electrónico"
          full_name: "Nombre completo"
          hispanic: "Hispano"
          personal_information: "Información personal"
          phone_number: "Número de teléfono"
          self_described_gender: "Género autodescrito"
          self_described_race: "Raza autodescrita" 
        person/hispanic:
          true: "Sí"
          false: "No"
      errors:
        models:
          person:
            attributes:
              birth_date:
                must_be_in_the_past: "no puede ser antes de hoy"
                must_be_formatted_correctly: "debe tener el formato yyyy-mm-dd"
              full_name:
                blank: "no puede estar en blanco"
              email:
                invalid: "no es válido. Debe parecerse a nombre@dominio.com"
              phone_number:
                invalid: "no es válido. Debe parecerse a 123-456-7890"

Gems like simple_form will label your forms with the correct languages, but you will have to call the model humanization helpers when outputting other types of content. You can also clean this up with your own helpers or presentation objets.

You manually pull transations like this:

  
  Person.human_attribute_name(:first_name) # -> First name
  Person.model_name.human # -> Person
  Person.model_name.human(count: 2) # -> People
  Person.human_attribute_name("hispanic.#{person.hispanic}") %> # -> Yes

Humanizing Context and Service Objects with I18n.

Sometimes it will make sense to humanize one object's names and attributes with a totally new name in different parts of an app. For example, maybe it makes sense on one screen to refer to Person ans Profile, or Household Member.

Sometimes it also makes sense to wrap a sequence of steps into a service object that someone can initiate by filling out a form and clicking a button.

I'll use something like what's below to accomplish that.

Now you can do things like Clients::ChangeProfile.model_name.human or Clients::ChangeProfile.human_attribute_name(:first_name).


module Clients
  class ChangeProfile < BaseCommand
    attribute :full_name, :string
    attribute :birth_date, :date
    attribute :email, :string
    attribute :phone_number, :string
    attribute :hispanic, :boolean, default: false
    attribute :race_list, default: []
    attribute :self_described_race, :string
    attribute :gender_list, default: []
    attribute :self_described_gender, :string
    attribute :user

    validates :user, presence: true


    def run
      context = {}
      validate!
      context[:person] = person

      # While the implementation is not shown in this code sample, the attributes
      # for this ActiveModel based Command/Service Object are written across
      # several models within a transaction
      save!

      result(true, **context)
    rescue ActiveRecord::RecordInvalid, ActiveModel::ValidationError
      rollup_errors(person) if person
      result(false, **context)
    end

    # overriding model name here, so this command can be bound to a form
    # with ActionView and humanized with full I18n support

    def self.model_name
      ActiveModel::Name.new(self, nil, 'Profile')
    end

    # other implementation details and methods
    # ...
    # ...
    # ...
  end
end


en:
  activerecord:
    models:
      person:
        one: Person
        other: People
      clients/profile:
        one: Profile
        other: Profiles
      household_member:
        one: Household Member
        other:  Household Members        
    attributes:
      person/hispanic:
        true: 'Yes'
        false: 'No'
      
    errors:
      models:
        person:
          attributes:  &person_error_attributes
            birth_date:
              must_be_in_the_past: "can't be before today"
              must_be_formatted_correctly: "must be formatted like yyyy-mm-dd"
            full_name:
              blank: "can't be blank"
            email:
              invalid: "is not valid. It should look like name@domain.com"
            phone_number:
              invalid: "is not valid. It should look like 123-456-7890"
        household_member:
          attributes:
            <<: *person_error_attributes

Navigational links and contexual information

I may place all of my navigational and contextual information into a locale file like what's below.

This enables me to do things like this:


  <%= link_to t(:add_action, subject: Person.model_name.human), new_manage_client_care_distribution_path, class: 'btn btn-info' %>


en:
  add: Add
  add_action: "Add %{subject}"
  all: All
  back: Back
  basic_information: Basic Information
  client_profile: Client Profile
  confirm: Are you sure?
  empty_search: "No %{subject} found"
  delete: Delete
  edit: Edit
  hello: "Hello world"
  history_action: "%{subject} History"  
  insights: Insights
  invite_action: "Invite %{subject}"  
  loading: Loading...
  provide_action: "Provide %{subject}"
  missing_object: "No %{subject}"
  new: New
  new_action: "New %{subject}"
  register_action: "Register %{subject}"
  summary: Summary
  view: View
  view_action: "View %{subject}"

Conclusion

I18n is powerful and flexible, and really makes it easy to humanize your applications. There are other complexities that I have not covered here, like right-to-left languages, supporting many languages at once, and long form content, but I hope this article has given you a good starting point.