Forem: Helder Burato Berto

Why I Built TracerKit

Helder Burato Berto — Mon, 06 Apr 2026 11:20:24 +0000

In a previous post, I described a workflow for building features with Claude Code: plan in conversation, save the plan as SPEC.md, implement task by task, /clear between sessions. The spec is the memory, the session is the execution.

I ended that post saying the workflow would change. It did.

Where the Manual Workflow Broke

The SPEC.md approach worked, but three problems kept surfacing:

Inconsistent specs. Every feature started from scratch. Some specs had decisions sections, some didn't. Some had task checklists, others had prose. Quality depended on how disciplined I was that day.
No verification. I'd mark tasks [x] by hand. Sometimes before tests passed. Sometimes I'd forget to update the spec entirely. The source of truth drifted from reality.
No lifecycle. Finished specs sat in the project root next to active ones. No archive, no status tracking, no way to see what was in flight.

I kept patching these with better prompts and more discipline. Then I realized the workflow itself should be the tool.

The Workflow Now

TracerKit is what came out of that realization. A set of AI agent skills (pure Markdown, zero runtime deps) that replace the manual spec workflow with a structured one.

Here's the same dark mode feature from the previous post, this time through TracerKit.

1. Orient

/tk:brief

At the start of any session, this shows what's in flight:

| Feature   | Status      | Age | Progress | Next                        |
|-----------|-------------|-----|----------|-----------------------------|
| dark-mode | in_progress | 1d  | 4/7      | Add accessible toggle label |

**Focus -> dark-mode**

One command to orient. No digging through files to remember where I left off.

2. Define the PRD

/tk:prd enable dark mode

The skill explores the codebase first, then interviews me one question at a time. It pushes back on vague answers, flags contradictions, and forces me to define scope boundaries before writing anything.

The output is a structured PRD at .tracerkit/prds/dark-mode.md with frontmatter tracking status:

---
created: 2026-04-06T10:00:00Z
status: created
---

# Dark Mode

## Problem Statement
...

## User Stories
1. As a user, I want to toggle between light and dark themes...

## Implementation Decisions
...

## Out of Scope
...

Every PRD follows the same structure. No more specs that vary by discipline level.

3. Plan in Tracer-Bullet Slices

/tk:plan dark-mode

The skill reads the PRD, explores the codebase, and breaks the feature into tracer-bullet vertical slices, a concept from The Pragmatic Programmer.

Instead of building layer by layer (all schema, then all services, then all UI), each phase cuts a thin path through every layer and is demoable on its own. Integration problems surface in phase 1, not at the end.

## Phase 1 — Theme toggles end-to-end

### Done when

- [ ] `useTheme` hook reads/writes localStorage
- [ ] `ThemeProvider` applies theme class on mount
- [ ] Toggle button in Header switches theme
- [ ] No flash of wrong theme on reload

---

## Phase 2 — Polish and accessibility

### Done when

- [ ] System preference used as default when no localStorage value
- [ ] Toggle has accessible label and keyboard support
- [ ] All tests pass

The key difference from a flat task list: each phase is independently verifiable. The "Done when" items are testable conditions, not prose. An agent can verify them by reading files or running commands.

4. Implement Phase by Phase

@.tracerkit/plans/dark-mode.md do phase 1

Same as before: reference the plan, implement, run tests. But the plan has structure that survives context loss. Each phase has explicit acceptance criteria. I don't need to re-explain what "done" means.

Between phases, /clear. The plan is the memory.

5. Verify and Archive

/tk:check dark-mode

This is the step that didn't exist before. The skill launches a read-only review agent that checks every "Done when" item against the actual codebase. It runs the test suite, compares user stories from the PRD against behavior, and reports findings:

## Verification: dark-mode

### Status: done

### Progress
Phase 1 — Theme toggles end-to-end: 4/4
Phase 2 — Polish and accessibility: 3/3
Total: 7/7

### BLOCKERS
- None

### SUGGESTIONS
- None

On done, it archives the PRD and plan to .tracerkit/archives/dark-mode/ and cleans up the active files. No stale specs sitting in the project root.

What Changed, What Didn't

Before (manual SPEC.md)	After (TracerKit)
Spec structure varies per feature	Same structure every time via interview
Tasks marked done by hand	Verification agent checks against codebase
Finished specs accumulate	Auto-archived on completion
No cross-feature visibility	`/tk:brief` dashboard
Flat task lists	Phased tracer-bullet slices
Decisions drift mid-session	Architectural decisions locked in plan header

What didn't change:

CLAUDE.md still defines how to work. TracerKit defines what to build.
/clear between phases. The plan is the context, not the conversation.
TDD during implementation. TracerKit structures the spec work, not the coding.
The spec is still a Markdown file. No database, no server, no lock-in.

The core habit is the same: write down what you're building before you build it. TracerKit made the habit consistent and added the verification step I was too lazy to do manually.

The Core Idea

Same as before, with one addition:

The spec is the memory. The session is the execution. Verification closes the loop.

Without verification, specs become wish lists. Tasks get marked done without evidence. /tk:check forces honesty: either the codebase matches the plan or it doesn't.

The other addition: lifecycle. Features have a clear path: created -> in_progress -> done -> archived. At any point, /tk:brief shows where everything stands.

Not every task needs the full workflow. A one-line fix or a small config change doesn't need a PRD and a phased plan. Use your judgment. That said, I've had consistent success following the full flow even for tasks that seemed small at first. Small tasks have a way of growing, and the spec catches that early.

Get Started

TracerKit is open source and stack-agnostic. It currently supports Claude Code, with Cursor and Copilot on the roadmap.

npm install -g tracerkit
tracerkit init

Repository: github.com/helderberto/tracerkit

The idea for TracerKit came out of Claude Code for Real Engineers, a cohort by Matt Pocock. The hands-on approach to building real things with Claude Code made the friction in my manual workflow impossible to ignore.

The entire project was built using its own workflow. Dog-fooding from day one. The walkthrough above is a real example, not a demo.

Ideas, feedback, and feature requests are welcome as GitHub issues.

The previous workflow was the right instinct: structure your AI sessions around a living spec. TracerKit is what happens when you stop maintaining that structure by hand and let the tools enforce it.

AI tooling will keep evolving. The habit of specifying before building won't.

If you try TracerKit, I'd like to hear how it fits your workflow. Share what worked, what didn't, and what's missing. The best features so far came from real usage, not guesses. Open an issue with ideas, friction points, or your own spec-driven flow. Building in public works better when the feedback loop is open.

Related:

How I Use Claude Code to Build Features

Helder Burato Berto — Thu, 26 Mar 2026 15:23:10 +0000

This is how I'm building features with Claude Code right now. AI tooling is evolving fast and this workflow will likely change. I'll write a follow-up when it does.

The Problem

Claude Code loses coherence as context fills. Long sessions accumulate noise: early decisions get buried, the agent starts contradicting prior agreements, or repeats work already done.

The instinct is to keep sessions alive to preserve context. This is backwards. A well-structured SPEC.md is more reliable than conversation history, and the cost of not having one adds up fast.

Why This Matters

Context loss isn't just annoying. It's expensive.

Without a spec, you spend sessions re-explaining what you already agreed on. Claude regenerates code it already wrote. You catch contradictions only after they're merged. A 2-hour feature stretches into 6 hours of back-and-forth.

The cost compounds: you start second-guessing the AI's output, micromanaging every change, or abandoning the session entirely and starting over. The tool that should multiply your speed becomes a source of friction.

A living spec eliminates this. The AI reads the same source of truth every time. You stop being a context manager and go back to being an engineer.

The Workflow

1. Plan Mode First

Before writing any code, I switch to plan mode using Shift+Tab in Claude Code, then describe the feature. I end the prompt asking Claude to generate a SPEC.md once we finish the planning session:

I want to add a dark mode toggle that persists across sessions.
The preference should be stored in localStorage and applied on initial render.

Let's discuss the approach, identify the files involved, and clarify any open questions.
At the end of our planning, generate a SPEC.md with the agreed context, tasks, and decisions.

The @ syntax in Claude Code lets you reference files directly in your prompt. Use it to point at existing files during planning so Claude has the right context before proposing anything:

@src/components/Header.tsx @src/hooks/

I want to add a dark mode toggle to the Header.
Let's plan the approach before writing any code.
At the end, generate a SPEC.md.

Plan mode keeps Claude from jumping straight to implementation. We brainstorm, I push back on things that don't fit, and only after the plan is solid does anything get written to disk.

2. Save the Plan as SPEC.md

Once I'm happy with the plan, I save it to SPEC.md at the project root. A task checklist is more useful than prose:

# Dark Mode Toggle

## Context

Persist user theme preference using localStorage. Apply on initial render to avoid flash.

## Approach

- Store preference as `theme` key in localStorage (`"dark"` | `"light"`)
- Read on mount in `ThemeProvider`, default to system preference if unset
- Toggle button in `Header`, updates state and localStorage in sync

## Tasks

- [ ] Add `useTheme` hook in `src/hooks/useTheme.ts`
- [ ] Update `ThemeProvider` to read from localStorage on mount
- [ ] Add toggle button to `Header` component
- [ ] Write unit tests for `useTheme`
- [ ] Write integration test for persistence across render

## Decisions

- No server-side preference (client only for now)
- System preference as fallback, not default dark

The ## Decisions section matters. Decisions made during planning get forgotten. Writing them down prevents re-litigating the same tradeoffs mid-implementation.

Keep the spec to: feature context, chosen approach, task checklist, and key decisions. Implementation details belong in the code. The spec should be small enough to reread in 30 seconds.

3. Implement

When starting a new session to implement, I always reference the spec explicitly using @:

@SPEC.md Continue from the next unchecked task.

Using @SPEC.md ensures the file content is injected directly into the context. Claude isn't guessing. It has the full spec in front of it before writing a single line.

Things like TDD, code style, and commit conventions are already defined in my CLAUDE.md. I don't repeat them in the spec or in the session prompt. The spec's only job is to describe what we're building, not how to behave.

File	Purpose	Lifespan
`CLAUDE.md`	How to work (style, linting, test commands)	Permanent / project-wide
`SPEC.md`	What to build (requirements, tasks, decisions)	Ephemeral / feature-specific

4. Mark Tasks Done, Update the Spec

As each task finishes, I mark it [x]:

- [x] Add `useTheme` hook in `src/hooks/useTheme.ts`
- [x] Update `ThemeProvider` to read from localStorage on mount
- [ ] Add toggle button to `Header` component

If the approach changes mid-implementation, I update ## Decisions before continuing. The spec reflects reality, not the original plan.

If a task turns out heavier than expected, I stop and break it into sub-tasks directly in the spec before continuing:

- [ ] Add toggle button to `Header` component
  - [ ] Create `ThemeToggle` component
  - [ ] Wire toggle to `useTheme` hook
  - [ ] Add accessible label and keyboard support

Then /clear and resume from the first sub-task. Same pattern, smaller scope.

5. `/clear` and Resume

Resuming a session:

@SPEC.md Continue from the next unchecked task.

One sentence. Claude reads the file, sees what's done, and picks up exactly where things left off.

Pausing mid-session:

We are pausing here. Update SPEC.md with our current progress, mark completed tasks,
and add a note under a "## Next Steps" section for the next session. Then I will /clear.

This keeps the spec accurate even when a session ends mid-task.

When to /clear:

After writing the SPEC, before starting implementation
After completing a task and marking it done
When the agent starts contradicting prior decisions
Between independent features

Don't clear mid-task. Finish it, mark it done, then clear.

Agents Along the Way

The SPEC.md is the backbone, but it's not the whole picture. Throughout the workflow I also trigger specialized agents at key moments. For example, a code-reviewer agent at the end of implementation to catch issues before committing.

Claude Code supports custom agents and there are several I rely on regularly. That's a topic for a future post.

The Core Idea

The spec is the memory. The session is the execution.

Every session starts by reading the spec. Every meaningful decision gets written back to it. When the session ends, nothing is lost. The spec has everything the next session needs to continue.

/clear isn't losing context. It's releasing noise and starting clean against a reliable source of truth.

But the spec isn't just for AI. It's also:

Onboarding docs for teammates picking up the feature mid-flight
A PR description template that explains what changed and why
A reference when debugging months later ("why did we choose cookies over localStorage?")

The spec starts as an AI tool. It ends as an engineering artifact.

Wrapping Up

This workflow won't stay the same forever. AI tooling is moving fast and what works today will likely look primitive in a year. But the core habit of writing down what you're building before you build it is older than AI and will outlast it.

I came across Martin Fowler's writing on Spec-Driven Development after settling into this workflow. He covers tools like spec-kit that formalize parts of this process. I haven't tried them yet, but the underlying idea is the same: keep a living spec as the anchor between AI sessions.

The spec is just a file. The discipline is what makes it work.

Related:

AI Writes Code. You Own Quality.

Helder Burato Berto — Tue, 24 Mar 2026 15:43:40 +0000

The more I use AI tools like Claude Code, the clearer it becomes: engineering skills are what make AI output worth shipping.

AI makes writing code faster. But shipping good software still requires the same judgment it always did. Speed without engineering discipline just means shipping bugs faster.

You Own the Code

AI is a tool in your toolset. Like a compiler, a linter, or a test runner. It doesn't own the code. You do.

When something breaks in production, nobody asks "which AI generated this?" They ask who shipped it. The PR has your name on it. The review was your responsibility. The decision to merge was yours.

AI is a multiplier. If your engineering skills are weak, it multiplies that too.

What AI Can't Do For You

Think about edge cases. AI covers the happy path. You guide it to the edges.
Understand the system. AI sees the file. You see the architecture.
Make tradeoffs. AI doesn't know your team's priorities, deadlines, or tech debt tolerance.
Carry team context. You were in the meeting where the team decided to deprecate that service. You know the naming conventions, the architectural decisions, the "we tried X and it didn't work" history. AI has none of that unless you provide it.

Guide AI With Tests

Red-Green-Refactor

TDD becomes even more powerful with AI. The engineer defines WHAT to test. AI handles the HOW.

Red. Write failing tests that cover expected behavior and edge cases:

describe('SearchFilter', () => {
  it('renders input with placeholder', () => {
    render(<SearchFilter onSearch={vi.fn()} />);
    expect(screen.getByPlaceholderText('Search products...')).toBeInTheDocument();
  });

  it('calls onSearch after user stops typing', async () => {
    const onSearch = vi.fn();
    render(<SearchFilter onSearch={onSearch} debounceMs={300} />);

    await userEvent.type(screen.getByRole('searchbox'), 'shoes');

    expect(onSearch).not.toHaveBeenCalled();
    await waitFor(() => expect(onSearch).toHaveBeenCalledWith('shoes'));
  });

  it('does not call onSearch for empty input', async () => {
    const onSearch = vi.fn();
    render(<SearchFilter onSearch={onSearch} debounceMs={300} />);

    await userEvent.type(screen.getByRole('searchbox'), 'a');
    await userEvent.clear(screen.getByRole('searchbox'));

    await waitFor(() => expect(onSearch).not.toHaveBeenCalled());
  });

  it('shows loading spinner while searching', () => {
    render(<SearchFilter onSearch={vi.fn()} isLoading />);
    expect(screen.getByRole('status')).toBeInTheDocument();
  });

  it('trims whitespace before calling onSearch', async () => {
    const onSearch = vi.fn();
    render(<SearchFilter onSearch={onSearch} debounceMs={300} />);

    await userEvent.type(screen.getByRole('searchbox'), '  shoes  ');
    await waitFor(() => expect(onSearch).toHaveBeenCalledWith('shoes'));
  });
});

You wrote zero implementation. But you defined the component's contract, its edge cases, and its behavior. That's engineering.

Green. AI implements the minimal code to pass all tests.

Refactor. You guide AI to clean up. Extract helpers, apply single responsibility, name things clearly. The goal: make it easy for the next engineer who touches this code.

Without test discipline, AI gives you untested code that "looks right." With TDD, AI works within constraints you defined.

Cover Entire Flows With E2E Tests

Unit tests verify pieces. E2E tests verify the whole flow works together.

AI can scaffold e2e tests, but you define which flows are critical. A checkout flow, an authentication sequence, a data export pipeline. These are decisions that require understanding the business, not just the code.

test('user completes checkout flow', async ({ page }) => {
  await page.goto('/products');
  await page.click('[data-testid="add-to-cart"]');
  await page.click('[data-testid="checkout"]');
  await page.fill('#email', 'test@example.com');
  await page.fill('#card-number', '4242424242424242');
  await page.click('[data-testid="place-order"]');
  await expect(page.locator('.confirmation')).toBeVisible();
});

You defined the critical path. AI can fill in the details, add assertions, handle setup/teardown. But the decision of WHAT to test end-to-end is yours. The same applies to edge cases: what happens when payment fails? When the session expires mid-checkout? When the cart is empty? You define those scenarios. AI writes the assertions.

Enforce Standards Before Code Ships

Standards only matter if they're enforced. Three layers:

Linting rules. Create rules that encode team conventions. AI follows them when configured, but you need to know which rules matter for your codebase.

Git hooks. Pre-push hooks that run linting and tests. Code that doesn't pass doesn't ship. No exceptions, not even for AI-generated code.

AI tool hooks. Tools like Claude Code support hooks that intercept actions and enforce standards automatically. Run lint before every commit. Run tests before every push. The AI operates within guardrails you defined.

The engineer's job: define the guardrails. AI works within them.

Close the Loop With Verification Tools

Every AI-generated change needs verification. The faster you catch problems, the faster AI can fix them.

Verification feedback loops exist at every level: CI pipelines that run visual regression tests, browser automation that captures screenshots, performance audits that flag regressions. The principle is the same. Every output becomes input for the next iteration.

In my workflow, I use Playwright MCP and Chrome DevTools MCP to close this loop directly inside the AI session:

Screenshot shows a broken layout? AI fixes the CSS.
Console error from a missing prop? AI adds the prop.
Lighthouse audit flags an accessibility issue? AI adds the missing aria label.
Network tab shows a redundant API call? AI refactors the data fetching.

This turns AI from "generate and hope" into "generate, verify, iterate." The engineer who sets up this loop gets better results than one who just prompts and ships.

The skill isn't writing the code. It's knowing what to verify and how to feed that information back.

Review AI Output Like You'd Review a Junior's PR

AI-generated code compiles. It passes the tests you wrote. It looks reasonable. But that doesn't mean it's good.

Read the diff. Every line. Look for:

Unnecessary complexity. AI loves abstractions. Does this need a factory pattern, or would a plain function do?
Subtle bugs. Off-by-one errors, missing null checks, race conditions. AI generates plausible code, not provably correct code.
Deviations from patterns. Your codebase uses a specific error handling pattern. AI might invent a different one.
Security holes. Unsanitized input, exposed secrets, missing auth checks. AI doesn't think adversarially by default.

The skill of reading code critically matters more when someone (or something) else writes it. You can't review what you don't understand. Invest in reading code as much as writing it.

Comment the Why, Not the How

AI tends to over-comment. It explains the obvious:

// Loop through the array and filter items
const filtered = items.filter(item => item.active);

// Set the state with filtered items
setItems(filtered);

These comments add noise. The code already says HOW it works.

Good comments explain why something exists or what business logic it represents:

// Archived items are processed by a nightly batch job, not shown in the UI
const filtered = items.filter(item => item.active);

But before writing any comment, ask: can the code explain itself? A well-named function or variable often eliminates the need for a comment entirely. Comments should exist only when the code can't tell the full story on its own.

That's the difference between AI-generated noise and engineering judgment.

Small Chunks for the Next Engineer

AI generates 500 lines in seconds. Your job: break it into reviewable, understandable pieces.

Extract functions. Apply single responsibility. Name things clearly. The next engineer (or the next AI session) touching this code benefits from clean structure.

This is a human judgment call. AI optimizes for the current prompt. You optimize for the project's lifetime. A function that does one thing well is easier to test, easier to reuse, and easier to replace than a monolith that "works."

Small PRs > big PRs, even when AI writes them.

Takeaways

You own the code. AI is a tool, not an excuse. Your name is on the PR.
TDD guides AI. Write failing tests first, let AI implement, then refactor.
E2E tests catch what unit tests miss. Define the critical flows and edge cases.
Enforce standards with linting and hooks. Guardrails before code ships.
Close the loop. Feed screenshots, errors, and audits back to AI for better iterations.
Review like it's a junior's PR. Read every line. Question every abstraction.
Comment the why, not the how. Business context over implementation details.
Small chunks > big dumps. Break AI output into pieces the next engineer can follow.

Wrapping Up

AI didn't make engineering skills optional. It made them the differentiator.

AI is a tool. A powerful one. But tools don't ship software, engineers do. Study the fundamentals. Master testing. Understand your architecture. Define your standards. Then use AI to execute at a speed you never could alone.

The code is AI's job. The quality is yours.

Claude Code Hooks

Helder Burato Berto — Thu, 19 Mar 2026 17:05:16 +0000

Claude Code moves fast: editing files, running commands, pushing code in quick succession. Hooks let you intercept that flow and enforce your standards automatically.

What Are Hooks?

Hooks are shell commands that run at lifecycle events during a Claude Code session. They're configured in settings.json and execute outside Claude's control. The harness runs them, not the AI.

This matters: Claude can't skip hooks or work around them. They're infrastructure, not suggestions.

Hook Types

Hook	When it runs	Can block?
`PreToolUse`	Before a tool executes	Yes (non-zero exit)
`PostToolUse`	After a tool executes	No
`Notification`	When Claude sends a notification	No
`Stop`	When Claude's turn ends	No
`SubagentStop`	When a subagent finishes	No

PreToolUse is the most powerful: it can stop a tool from running entirely.

Configuration

Hooks live in settings.json. Two scopes:

~/.claude/settings.json (global, applies everywhere)
.claude/settings.json (project-level, merged with global)

Structure:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "your-shell-command-here",
            "timeout": 60,
            "statusMessage": "Running check..."
          }
        ]
      }
    ]
  }
}

Fields:

matcher: tool name to match ("Bash", "Edit", "Write", "" for all)
command: shell command to run
timeout: milliseconds before the hook is killed
statusMessage: shown in the UI while the hook runs

Hook Input

Hooks receive the tool's input via stdin as JSON. Use jq to extract what you need:

# Get the bash command being run
cmd=$(jq -r '.tool_input.command')

# Get the file path being edited
path=$(jq -r '.tool_input.file_path')

This lets you write conditional hooks that only fire for specific operations.

Practical Examples

Lint Before Push

Block git push unless lint passes:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "cmd=$(jq -r '.tool_input.command'); echo \"$cmd\" | grep -q 'git push' || exit 0; npm run lint",
            "timeout": 120,
            "statusMessage": "Running lint before push..."
          }
        ]
      }
    ]
  }
}

exit 0 on non-push commands lets them through. Only push triggers the lint check. Lint fails = push blocked.

Type-Check After TypeScript Edits

Run tsc after editing .ts files:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "path=$(jq -r '.tool_input.file_path'); echo \"$path\" | grep -q '\\.ts$' || exit 0; npx tsc --noEmit",
            "timeout": 60,
            "statusMessage": "Type-checking..."
          }
        ]
      }
    ]
  }
}

Desktop Notification When Claude Stops

Know when a long task finishes without watching the terminal:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude finished\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Block Writes to Sensitive Files

Prevent accidental edits to .env files:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "path=$(jq -r '.tool_input.file_path'); echo \"$path\" | grep -q '\\.env' && echo 'Blocked: cannot write to .env files' && exit 1 || exit 0"
          }
        ]
      }
    ]
  }
}

Non-zero exit blocks the tool. Claude sees the output and adjusts.

Frontend-Specific Examples

Run Tests After Component Changes

Trigger Vitest after editing React components:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "path=$(jq -r '.tool_input.file_path'); echo \"$path\" | grep -qE '\\.(tsx|jsx)$' || exit 0; npx vitest run --reporter=verbose 2>&1 | tail -20",
            "timeout": 120,
            "statusMessage": "Running component tests..."
          }
        ]
      }
    ]
  }
}

Only fires on .tsx/.jsx edits. You see failing tests immediately, not after the next push.

Block `console.log` Before Commit

Prevent debug statements from shipping:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "cmd=$(jq -r '.tool_input.command'); echo \"$cmd\" | grep -q 'git commit' || exit 0; git diff --cached | grep -q 'console\\.log' && echo 'Blocked: staged changes contain console.log' && exit 1 || exit 0",
            "statusMessage": "Checking for console.log..."
          }
        ]
      }
    ]
  }
}

Scans the staged diff before every commit. Fails if console.log is found.

ESLint on Every File Write

Catch lint errors the moment a file is created:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "path=$(jq -r '.tool_input.file_path'); echo \"$path\" | grep -qE '\\.(ts|tsx|js|jsx)$' || exit 0; npx eslint \"$path\" --max-warnings=0",
            "timeout": 30,
            "statusMessage": "Linting new file..."
          }
        ]
      }
    ]
  }
}

Useful when Claude writes new files from scratch. Errors surface before any follow-up edits build on broken code.

Accessibility Check After Component Edits

Run axe-core via CLI after touching UI components:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "path=$(jq -r '.tool_input.file_path'); echo \"$path\" | grep -q 'components/' || exit 0; echo \"$path\" | grep -qE '\\.tsx$' || exit 0; npx axe-cli http://localhost:3000 --exit",
            "timeout": 60,
            "statusMessage": "Checking accessibility..."
          }
        ]
      }
    ]
  }
}

Requires a running dev server. Best paired with a PreToolUse hook that starts it if not running.

Prettier Format Check After Write

Enforce consistent formatting on new files without running format-on-save globally:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "path=$(jq -r '.tool_input.file_path'); echo \"$path\" | grep -qE '\\.(ts|tsx|css|json)$' || exit 0; npx prettier --check \"$path\" || (echo \"Run: npx prettier --write \\\"$path\\\"\" && exit 1)",
            "timeout": 15,
            "statusMessage": "Checking formatting..."
          }
        ]
      }
    ]
  }
}

Outputs the fix command when it fails, so Claude can auto-correct.

Hooks vs. CLAUDE.md

CLAUDE.md tells Claude what to do. Claude might forget or skip steps under pressure.

Hooks run regardless of what Claude does. They're external to the AI.

Use CLAUDE.md for preferences. Use hooks for guarantees.

Example: "Run lint before committing" in CLAUDE.md = a suggestion. A PreToolUse hook on Bash that checks for git commit = enforced.

Ordering Multiple Hooks

You can stack hooks on the same event:

{
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "check-push-lint.sh"
        },
        {
          "type": "command",
          "command": "check-push-secrets.sh"
        }
      ]
    }
  ]
}

Hooks run in order. First failure blocks the rest.

What I Use Hooks For

Lint before push (catches style errors before CI)
Type-check on edit (immediate feedback on TypeScript errors)
Tests after component changes (know immediately if something broke)
console.log guard on commit (never ship debug statements)
Secret scanning on push (last line of defense before remote)
Notifications on stop (no more watching the terminal)

When Not to Use Hooks

The real cost isn't latency. A grep or jq command adds single-digit milliseconds. The cost is pairing a slow operation with a high-frequency tool call.

Avoid:

Pairing heavy operations with broad matchers. Running tsc --noEmit on every Edit recompiles the full project each time. Scope it to Bash and trigger only on git push.
Overly broad matchers. If your hook only cares about .ts files, don't match all Write calls and filter inside the script. Use the most specific matcher you can.

Lightweight checks (grep, jq, file path tests) are essentially free. Save the heavy tools (tsc, vitest, npm run build) for infrequent triggers like git push or git commit.

Wrapping Up

Hooks are the difference between hoping Claude does the right thing and knowing it will.

Your CI catches broken builds. Your hooks catch them before the push. The earlier you catch problems, the cheaper they are to fix.

Define your quality gates once. Let hooks enforce them on every session.

Further reading:

Building Shareable AI Agent Skills

Helder Burato Berto — Fri, 13 Feb 2026 11:36:54 +0000

You're typing the same instructions to Claude Code every session. "Create a commit following repo style." "Run tests before pushing." "Check coverage on these changes."

What if those workflows were reusable slash commands? What if they worked in Cursor, Continue, and Cline too?

That's what Skills are - version-controlled AI workflows that work across agents.

The Problem

AI agents lose context between sessions. Every new chat, you're re-explaining:

Git workflow preferences
PR creation templates
Testing requirements
Quality gates before shipping

You're doing the AI's job - providing context - instead of letting it do yours.

The Solution: Skills as Code

Skills are markdown files that encode workflows. Install once, invoke with /skill-name.

/ship = stage, commit with style-matched message, push, verify.

No more manual git add -A && git commit && git push dance.

Why Skills Matter

Cross-agent portability - Write once, works in multiple agents:

Claude Code
Cursor
Continue
Cline
Windsurf
Replit
+ more

Version controlled - Skills are git-tracked markdown:

Iterate based on real usage
Roll back if needed
See what changed and why

Shareable - Install anyone's skills:

npx skills add helderberto/skills
npx skills add vercel-labs/agent-skills

Team workflows - Codify team conventions:

Commit message style
PR templates
Security checks
Quality gates

Context efficiency - Skills reduce token usage:

/ship uses fewer tokens than repeating full workflow instructions
Agent loads skill once, executes steps without re-explanation
Longer conversations stay within context window limits

Real Example: Evolving the Ship Skill

Started simple:

1. Stage all changes
2. Commit
3. Push

Hit a problem: Failed on non-Node projects when trying to run npm test.

Fix:

3. Check for quality checks:
   - If package.json exists, check for lint and test scripts
   - Run available checks in parallel
   - If no package.json, skip quality checks

Pushed update. Everyone benefits via npx skills update.

This is what version control for AI instructions looks like.

Building Your Skills Repo

1. Create repository structure:

skills/
├── ship/
│   └── SKILL.md
├── commit/
│   └── SKILL.md
└── coverage/
    └── SKILL.md

2. Write SKILL.md:

Example:

---
name: ship
description: "Stage all changes, commit, and push"
---

# Ship Changes

## Workflow

1. Run git status (never -uall)
2. Review all changes
3. Generate commit message matching repo style
4. Stage all files: git add -A
5. Commit with HEREDOC format
6. Push to current branch
7. Verify with git status

## Rules

- Match repo commit style from git log
- NEVER force push
- NEVER skip hooks
- Push to current branch only

3. Install:

npx skills add yourusername/skills --all

4. Use:

Example:

# In Claude Code, Cursor, Continue, etc.
/ship

My Skills Collection

I maintain a collection covering git workflows, quality gates, safety checks, and development practices at helderberto/skills.

Install: npx skills add helderberto/skills --all

Skills vs. Docs

Docs (CLAUDE.md) = passive instructions AI reads

Skills = active workflows AI executes

Key difference:

CLAUDE.md loads every session - takes context tokens upfront
Skills load only when invoked - no token cost until you use them

When to use each:

CLAUDE.md: Always-on rules (code style, immutability, testing principles)
Skills: On-demand workflows (commit, PR creation, coverage checks)

Docs say "prefer immutability." Skills enforce it by running lint checks before commit.

Example: Put "no array mutations" in CLAUDE.md. Put "/ship workflow with lint checks" in skills.

Both matter. Docs set standards. Skills enforce them. Skills save context for when you need it.

How Skills Work

The Skills CLI uses symlinks to share files across agents:

~/.agents/skills/ship/     # Source
~/.claude/skills/ship/     # Symlink for Claude Code
~/.cursor/skills/ship/     # Symlink for Cursor
~/.continue/skills/ship/   # Symlink for Continue

One file, multiple agent directories.

Update the source, all agents see the changes.

Discovery and Sharing

Find skills:

Example:

npx skills find typescript
npx skills find testing

Install specific skills:

Example:

npx skills add helderberto/skills --skill ship --skill commit

Install everything:

Example:

npx skills add helderberto/skills --all

Update all:

Example:

npx skills update

Browse more: skills.sh

Benefits in Practice

Before skills:

Example:

Repeat instructions every session
Inconsistent commit messages
Forget quality checks
Manual git commands

After skills:

/ship handles entire workflow
Commits match repo style automatically
Quality gates always run
Zero manual git operations

Impact:

Skills replace dozens of repeated prompts
Works across all my coding agents
Team members install same skills = consistent workflows
Improvements benefit everyone via update
Fewer tokens spent on context = longer, more productive conversations

Skills = Infrastructure for AI

This isn't about shortcuts. It's about encoding:

Team conventions (commit message style, PR templates, etc.)
Security practices
Quality gates (lint, test, coverage)
Organizational knowledge

Getting Started

Create skills repo
Write 2-3 workflows you repeat most
Install with npx skills add yourusername/skills
Iterate based on real usage
Share with team/community

Start small. My first skill was just "commit and push." It evolved from there.

Wrapping Up

You're already teaching AI agents your workflows. Skills make those teachings reusable, shareable, and version controlled.

Stop repeating yourself. Start building skills.

Resources:

My skills: github.com/helderberto/skills
Skills CLI: skills.sh
Vercel's collection: github.com/vercel-labs/agent-skills

Write once. Use everywhere. Improve continuously.

What Your Claude Code Agents Don't Need to Be Told

Helder Burato Berto — Mon, 09 Feb 2026 17:44:21 +0000

Claude Code has a finite context window. Every token matters. Your agent definitions, skill files, and docs all compete for that space with the actual code you're asking it to analyze.

The problem: it's tempting to write exhaustive agent configurations, detailed examples, scripted responses, repeated boilerplate. It feels like you're being thorough. But you're actually teaching the model things it already knows, while leaving less room for the things it doesn't.

I hit this wall while working on a frontend feature. My agents were loaded with generic programming examples, and I started wondering: is any of this actually helping, or is it just consuming context?

This is a follow-up to Teaching Claude Code Your Standards, where I covered the initial setup of ~/.claude/ with docs, skills, and agents.

The Real Problem: Teaching the Model What It Already Knows

My TypeScript enforcer agent included examples of how to use spread operators, how to write early returns, and when to use Set instead of Array.find(). The model already knows all of that.

What it doesn't know: our project uses a formatjs babel plugin with ast: true, which compiles i18n messages to AST at build time. This causes parameterized messages like {count} active to render variable names literally in tests. That's a gotcha worth documenting, it cost me real debugging time.

The distinction is simple: generic programming knowledge is noise. Project-specific knowledge is signal.

Three Filters for Every Line in Your Config

1. Does the model already know this?

The model knows common patterns. It knows early returns, immutability with spread, N+1 query problems, React memoization. Including examples of these doesn't make it better at applying them, it just takes up space.

Delete: Generic code examples, common design patterns, standard best practices.

Keep: Gotchas specific to your project, team conventions the model can't infer, configuration quirks that cause surprising behavior.

2. Is this repeated across agents?

I found identical sections copy-pasted across every agent:

## Commands to Use
- `Glob` - Find files
- `Grep` - Search for patterns
- `Read` - Examine content
- `Bash` - Run scripts

## Success Criteria
The agent is successful when...

The model already knows its available tools from the system prompt. "Success criteria" sections just reword the agent's description. These are filler.

3. Is this a checklist or an essay?

The model doesn't need you to explain how to extract a function. It needs to know when you want it flagged.

Before (essay with examples):

### Readability Review

Evaluate function complexity and cognitive load...

**Long functions example:**
// ⚠️ Too long (>50 lines)
const processOrder = (order) => {
  // ... 80 lines of logic
};

// ✅ Extracted
const validateOrder = (order) => { /* ... */ };
const calculateTotal = (order) => { /* ... */ };
...

After (checklist):

### Readability
- Functions >50 lines → extract
- Nesting >3 levels → early returns
- Magic numbers → named constants
- Unclear names

Same rules. The model fills in the how.

Agents vs Skills: Different Problems, Different Tools

I had a "dependency auditor" agent, hundreds of lines of instructions for what amounts to running npm audit and npm outdated. That's not a judgment call. That's a command sequence.

Agents solve problems requiring judgment: code review, test quality assessment, TypeScript enforcement. They need checklists of what to look for.

Skills solve problems with deterministic steps: commit, push, lint, audit. They need a sequence of commands and rules about when to stop.

The dependency auditor became a skill:

# Dependency Audit

## Commands
Run in parallel:
- `npm audit` - security vulnerabilities
- `npm outdated` - outdated packages

## Workflow
1. Run security audit and outdated check
2. Report critical vulnerabilities with fix commands
3. List outdated packages (major vs minor/patch)
4. Check for unused deps: grep imports in src/

## Rules
- Use `npm audit`, never `npx`
- Prioritize: security > major updates > unused > minor updates

Clear. Deterministic. No essays needed.

Overlapping Agents Dilute Focus

I had three agents doing related work:

code-review: logic errors, readability, pattern consistency
refactor-assistant: code smells, complexity, dead code, duplication
perf-analyzer: algorithm complexity, unnecessary re-renders, memoization

The overlap was significant. The refactor-assistant's unique value was a code smells checklist. The perf-analyzer's unique value was React-specific checks. Both fit naturally as sections in one focused code-review agent.

One agent with clear sections beats three agents competing for the same territory.

Your Workflows Should Fail Fast

My /ship skill (stage → commit → push) had no quality gates. It would happily push broken code. The fix was simple:

## Workflow
1. Review all changes
2. Run quality checks in parallel:
   - `npm run lint`
   - `npm test`
3. If checks fail: report errors, STOP do not commit or push
4. Generate commit message
5. Stage, commit, push

The key is the hard-stop rule. Without it, the skill optimizes for speed over correctness.

Document What Only You Know

The highest-value documentation is knowledge the model can't infer from your code alone:

Internationalization gotchas:

Whitespace between elements: use layout (Flex/gap) instead of {' '} - linters flag literal strings in JSX

Accessibility testing:

getByRole as primary query - if it can't find the element, the a11y is likely wrong
Prefer getByRole over container.querySelector - query by accessibility, not DOM structure

Team conventions:

vi.spyOn over vi.mock for your own code
vi.mock only for third-party libraries

These are decisions your team made. The model can't infer them from reading your code. They prevent real mistakes. That's what your config should contain.

What I Can't Prove

I can't prove this made my agents "better." There's no benchmark for agent configuration effectiveness. What I can say: the content I removed was generic programming knowledge the model already has. The content I kept, and added, is specific to my projects and workflows. Every token saved on instructions is a token available for analyzing actual code.

Whether that tradeoff matters depends on how close to the context limit you work. For long sessions with large codebases, it adds up.

Takeaways

Generic knowledge is noise: If the model already knows it, it doesn't belong in your config
Checklists over essays: Tell it what to check, not how
Skills for commands, agents for judgment: Match the tool to the problem
One focused agent beats three overlapping ones: Merge and consolidate
Document what only you know: Project gotchas, team conventions, configuration quirks
Workflows should fail fast: Add quality gates before destructive operations

Your Claude Code configuration should contain what only you know about your project. Everything else is already in the model.

My full config: github.com/helderberto/dotfiles

Teaching Claude Code Your Standards

Helder Burato Berto — Fri, 06 Feb 2026 11:28:22 +0000

Ever had an AI refactor your entire file when you asked for a one-line fix? Or add comments to every function?

Claude Code's power comes from configuration. Without clear instructions, it's chaotic. With them, it becomes an extension of your development standards. This article shows how I've configured Claude Code to enforce immutability, follow TDD, automate workflows, and maintain consistency.

Note: AI tooling moves fast. This reflects my current workflow.

Know What You're Doing First

Critical: Don't blindly trust AI output. You must understand what the code does before shipping it.

Claude Code is a productivity multiplier, not a replacement for engineering judgment. It automates patterns you already know, enforces standards you've already defined, and catches mistakes you'd catch in review - but faster.

Before using these configs:

Understand the fundamentals - Know why immutability matters, not just that it's a rule
Review every change - Read diffs before committing. AI makes mistakes.
Test everything - Run tests, check behavior. Don't assume it works.
Own the output - You ship it, you're responsible. AI is a tool, not an excuse.

The configs below work because I know what good code looks like in my context. They encode decisions I've already made. If you copy them without understanding why, you'll ship bad code faster.

Use AI to accelerate what you already know how to do well.

The `.claude/` Directory

Global config lives at ~/.claude/.

Structure:

~/.claude/
├── CLAUDE.md # Global instructions
├── docs/     # Conventions (git, typescript, testing, etc.)
├── skills/   # Custom slash commands
└── agents/   # Specialized workflows for specific tasks

Write Short, Prescriptive Docs

Forget lengthy style guides. Write terse, imperative docs. Examples:

Bad: "We generally prefer to avoid using any in TypeScript because it defeats the purpose of type safety."

Good: "No any - use unknown if needed"

Your docs become the AI's memory. Every session, it reads them.

Custom Skills = Workflow Automation

Skills are slash commands that trigger workflows. Mine:

/ship - Stage all, commit, push
/create-pr - Create PR with template
/coverage - Check test coverage on unstaged changes
/safe-repo - Scan for leaked secrets

Before: Manually running commands every deployment

# Manual commands
git add -A
git commit -m "fix: update validation logic"
git push
git status  # verify it worked

After: /ship - done

# Claude handles: status check, staging, commit with style-matched message, push, verification

Structure:

skills/ship/
└── skill.md

The markdown defines the workflow. AI executes it.

Enforce Immutability Through Instructions

I mandate immutability in code-principles.md:

## Immutability (mandatory)

- No array mutations: `push`, `pop`, `splice`, `shift`, `unshift`
- No object mutations: `obj.key=`, `delete obj.key`
- Use: spread `[...]`, `slice`, `map`, destructuring

The AI catches mutations I'd miss in review.

TDD By Default

My testing.md enforces test-first:

## Rules

- Prefer `vi.spyOn` over `vi.mock` for your own code
- Only use `vi.mock` for third-party libraries
- Test output must be pristine (zero warnings/errors)

Fewer mocks = more confidence.

Concision Is a Feature

My global instruction: "Extreme concision in all interactions and commits. Sacrifice grammar for brevity."

Results:

Faster responses
Less noise
Commit messages match my style

What Changes

Immutability enforcement:

AI catches mutations I'd miss in review
Array mutation bugs get caught before commit
Consistent patterns across codebase

Commit consistency:

Commits follow conventional commit style
Messages match my terse style
PR descriptions follow template structure

Code review:

Fewer style-related comments
Less back-and-forth on conventions
Reviews focus on logic, not formatting

Learnings

Invest in docs early - They compound. Every session benefits.
Skills > repetition - If you do it 3x, make it a skill.
Prescriptive > descriptive - "Do X" beats "we usually prefer X"
Test your instructions - AI follows literally. Ambiguity = inconsistency.
Version control your config - Treat .claude/ like code.

The Setup

# Global config
~/.claude/CLAUDE.md

# Project-specific overrides (optional)
.claude/PROJECT.md

AI reads both. Project overrides global.

My full config: github.com/helderberto/dotfiles

Result

Consistent code, faster reviews, fewer "why did you do that?" moments. The AI becomes an extension of your standards, not a wildcard.

Wrapping Up

AI without constraints is unpredictable. With clear docs, custom skills, and enforced standards, it becomes reliable.

Invest time upfront defining your standards. The AI will enforce them consistently across every session. No more hoping it does the right thing.

The config is the product. Treat it like code: version control it, test it, refactor it.

Teach once. Enforce forever.

Polymorphism with React

Helder Burato Berto — Sat, 04 Mar 2023 12:54:38 +0000

In this article, we will create an example using Polymorphism in React.

Acceptance Criteria

Create a LinkButton that render an element button or a depending on the href prop
The LinkButton component has an optional prop called href
If the href is provided, the component should render an a tag. Otherwise, it should render a button tag

Solving the Problem without Polymorphism

import React from 'react'

export default function LinkButton({ href, children }) {
  if (href) {
    return <a href={href}>{children}</a>
  }

  return <button>{children}</button>
}

It solves our problem, but imagine if we need to pass the rest of props to the component.

It will involve updating the button and the a, like the following example:

import React from 'react'

export default function LinkButton({ href, children, ...props }) {
  if (typeof href === 'string') {
    return (
      <a href={href} {...props}>
        {children}
      </a>
    )
  }

  return <button {...props}>{children}</button>
}

And for every case you want to add props, you gonna need to maintain both cases, so much work, right?

Solving the Problem with Polymorphism

Let's create the same example using Polymorphism:

import React from 'react'

export default function LinkButton({ href, children, ...props }) {
  const Tag = typeof href === 'string' ? 'a' : 'button'

  return (
    <Tag href={href} {...props}>
      {children}
    </Tag>
  )
}

You may be asking, and what about the href being passed to the button?

Since it will be undefined React will take control to avoid rendering this property to our HTML.

Wrapping Up

Keeping this approach in mind, you can create a component that handles the logic you want, and it will be easier to give maintenance.

I hope this tip was useful for you!

Integrating TLDR with FZF

Helder Burato Berto — Sun, 26 Feb 2023 10:05:23 +0000

In this post, we gonna dive into TLDR with fzf search.

Usage of TLDR

Go to your favorite terminal, with TLDR enabled, and execute the following command:

$ tldr brew

Searching with FZF

$ fzf .

It will execute a fuzzy search in the current directory.

Passing a TLDR list to FZF

$ tldr --list | fzf

The first argument tldr --list will generate a list of available commands enabled in your command line.

And when passing with a pipe operator | it will send the results to fzf.

Selecting an Argument with FZF

$ tldr --list | fzf | xargs tldr

As you did in the previous step, it will share the list to fzf, and when you select an option it will send the argument via xargs to execute with tldr.

Previewing Commands on Searching

It creates a preview window, showing the results from TLDR and passing to the new window via xargs.

Let's try with the following command:

$ tldr --list | fzf --preview "tldr {1}" --preview-window=right,60% | xargs tldr

Bonus: Aliasing

Create an alias to avoid remembering all this stuff:

alias tldrf='tldr --list | fzf --preview "tldr {1}" --preview-window=right,60% | xargs tldr'

Source your command line configuration file, in my case it is .zshrc, and voilá!

Try your new alias into the command line:

$ tldrf

Effects with React useEffect

Helder Burato Berto — Wed, 22 Feb 2023 10:58:41 +0000

Some practical examples of how to use the React useEffect() -

import React from "react";

export default function App() {
  const [name, setName] = React.useState('');
  const [age, setAge] = React.useState(0);

  React.useEffect(() => {
    console.log('component mounted');

    return () => {
      console.log('component unmounted');
    }
  }, []); // empty array means it will only run on mounting

  // Separation of concerns
  // This is a good example of how to separate concerns splitting into two useEffects to handle each value
  React.useEffect(() => {
    console.log('name changed', name);
  }, [name]); // only triggers when name changes

  React.useEffect(() => {
    console.log('age changed', age);
  }, [age]); // only triggers when age changes

  return (
    <div>
      <input type="text" value={name} onChange={e => setName(e.target.value)} />
      <input type="number" value={age} onChange={e => setAge(e.target.value)} />
    </div>
  );
}

On Mounting

Similar to the legacy componentDidMount it will trigger on mounting the component:

React.useEffect(() => {
  console.log('component mounted');

  return () => {
    console.log('component unmounted');
  }
}, []); // empty array means it will only run on mounting

On Changing Values

React.useEffect(() => {
  console.log('name changed', name);
}, [name]); // only triggers when name changes

Separation of Concerns

Instead of watching two values at the same useEffect, like the following:

React.useEffect(() => {
  console.log({ name, age });
}, [name, age]);

Think in separation of concerns, and split each it will be cleaner and easier for the next person who need to read your code, eg:

// Separation of concerns
// This is a good example of how to separate concerns splitting into two useEffects to handle each value
React.useEffect(() => {
  console.log('name changed', name);
}, [name]); // only triggers when name changes

React.useEffect(() => {
  console.log('age changed', age);
}, [age]); // only triggers when age changes

Manipulating the DOM with React Ref

Helder Burato Berto — Wed, 22 Feb 2023 10:57:02 +0000

When you found something like document.querySelector('.something') in your React codebase, it's probably a code smell.

To manipulate the DOM you should consider using "ref" - React Docs - ref

After rendering the DOM element, it will enable the DOM node and its methods to be called.

To ensure the "inputRef.current" will be available at the moment of the trigger "focus()", you can do an "early return" to bail out the effect early, like the following snippet:

import React from "react";

export default function App() {
  const inputRef = React.useRef(null);

  React.useEffect(() => {
    if (!inputRef.current) {
      return;
    }

    inputRef.current.focus();
  }, [])

  return <input ref={inputRef} type="text" />;
}

Controlled vs Uncontrolled Elements

Helder Burato Berto — Fri, 03 Feb 2023 10:27:05 +0000

When working with React, you will notice often used naming called Controlled and Uncontrolled.

So, what do it mean? Let's dive into it.

Uncontrolled Element

This type of element is not managed by React.

In the following example, you have an uncontrolled input element:

import React from 'react'

export default function UncontrolledInput() {
  return (
    <input
      value="Empty Value"
      onChange={() => console.log('It wont update the value.')}
    />
  )
}

Notice the component isn't doing anything, just printing an empty value Empty value.

You can't update, nor delete the value.

Let's add an event handler for updating the value state:

import React from 'react'

export default function UncontrolledInput() {
  const [value, setValue] = React.useState()

  return (
    <>
      <input
        value={value}
        onChange={(event) => setValue(event.target.value)}
      />
      <p>Current value: {value}</p>
    </>
  )
}

Notice that even if we can update the input now, you have a warning on your browser console. Like the following:

Warning: A component is changing an uncontrolled input to be controlled. This is likely caused by the value changing from undefined to a defined value, which should not happen. Decide between using a controlled or uncontrolled input element for the lifetime of the component.

Why is this happening?

Since the default value is not initialized in the useState(), React will consider the initial value as undefined, so it means the input still uncontrolled at the first render.

It only will be controlled when the user starts typing on the input.

Controlled Element

The Controlled element is an element that is managed the event and values by React.

Let's create an input managed by React:

import React from 'react'

export default function ControlledInput() {
  const [value, setValue] = React.useState('') // Start as an empty string

  return (
    <>
      <input
        value={value}
        onChange={(event) => setValue(event.target.value)}
      />
      <p>Current name: {value}</p>
    </>
  )
}

Since you set it as an empty string, it will be a controlled element.

When the user starts typing in the input, the onChange event updates the value of name from '' to a new string.

Wrapping Up

It's a common mistake updating uncontrolled elements to controlled raising this kind of warning.

When you understand how it works, it's easier to avoid these issues.

Forem: Helder Burato Berto

Why I Built TracerKit

Where the Manual Workflow Broke

The Workflow Now

1. Orient

2. Define the PRD

3. Plan in Tracer-Bullet Slices

4. Implement Phase by Phase

5. Verify and Archive

What Changed, What Didn't

The Core Idea

Get Started

How I Use Claude Code to Build Features

The Problem

Why This Matters

The Workflow

1. Plan Mode First

2. Save the Plan as SPEC.md

3. Implement

4. Mark Tasks Done, Update the Spec

5. /clear and Resume

Agents Along the Way

The Core Idea

Wrapping Up

AI Writes Code. You Own Quality.

You Own the Code

What AI Can't Do For You

Guide AI With Tests

Red-Green-Refactor

Cover Entire Flows With E2E Tests

Enforce Standards Before Code Ships

Close the Loop With Verification Tools

Review AI Output Like You'd Review a Junior's PR

Comment the Why, Not the How

Small Chunks for the Next Engineer

Takeaways

Wrapping Up

Claude Code Hooks

What Are Hooks?

Hook Types

Configuration

Hook Input

Practical Examples

Lint Before Push

Type-Check After TypeScript Edits

Desktop Notification When Claude Stops

Block Writes to Sensitive Files

Frontend-Specific Examples

Run Tests After Component Changes

Block console.log Before Commit

ESLint on Every File Write

Accessibility Check After Component Edits

Prettier Format Check After Write

Hooks vs. CLAUDE.md

Ordering Multiple Hooks

What I Use Hooks For

When Not to Use Hooks

Wrapping Up

Building Shareable AI Agent Skills

The Problem

The Solution: Skills as Code

Why Skills Matter

Real Example: Evolving the Ship Skill

Building Your Skills Repo

My Skills Collection

Skills vs. Docs

How Skills Work

Discovery and Sharing

Benefits in Practice

Skills = Infrastructure for AI

Getting Started

Wrapping Up

What Your Claude Code Agents Don't Need to Be Told

The Real Problem: Teaching the Model What It Already Knows

Three Filters for Every Line in Your Config

1. Does the model already know this?

2. Is this repeated across agents?

3. Is this a checklist or an essay?

Agents vs Skills: Different Problems, Different Tools

Overlapping Agents Dilute Focus

5. `/clear` and Resume

Block `console.log` Before Commit

The `.claude/` Directory