DEV Community: Ryu0705

How to Build a Free API with Cloudflare Workers (Zero Infrastructure Cost)

Ryu0705 — Sun, 22 Mar 2026 14:32:39 +0000

Running an API usually means paying for servers. But Cloudflare Workers lets you deploy production-ready APIs on a generous free tier: 100,000 requests per day, zero cold starts, and global edge deployment. Here's how to build one from scratch.

What You Get for Free

Cloudflare Workers free tier includes:

100,000 requests/day
10ms CPU time per request (enough for most APIs)
KV Storage: 100,000 reads/day, 1,000 writes/day
Global deployment across 300+ data centers
Custom domains via Cloudflare DNS

For personal projects, internal tools, and moderate-traffic APIs, this is more than enough.

Setting Up

Install Wrangler

Wrangler is Cloudflare's CLI for Workers development.

npm install -g wrangler
wrangler login

Create a New Project

wrangler init my-api
cd my-api

This generates a basic project with wrangler.toml and src/index.js.

Configure wrangler.toml

name = "my-api"
main = "src/index.js"
compatibility_date = "2026-03-01"

[vars]
API_VERSION = "1.0.0"

[[kv_namespaces]]
binding = "CACHE"
id = "your-kv-namespace-id"

Create the KV namespace:

wrangler kv namespace create CACHE
# Copy the output id into wrangler.toml

Building the Router

Workers receive a fetch event. Here's a clean routing pattern without any external dependencies:

// src/index.js
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    const path = url.pathname;
    const method = request.method;

    // CORS headers
    if (method === 'OPTIONS') {
      return handleCors();
    }

    try {
      // Route matching
      if (path === '/api/health' && method === 'GET') {
        return json({ status: 'ok', version: env.API_VERSION });
      }

      if (path === '/api/data' && method === 'GET') {
        return await handleGetData(url, env);
      }

      if (path === '/api/data' && method === 'POST') {
        return await handlePostData(request, env);
      }

      return json({ error: 'Not found' }, 404);
    } catch (err) {
      return json({ error: 'Internal server error' }, 500);
    }
  }
};

function json(data, status = 200) {
  return new Response(JSON.stringify(data), {
    status,
    headers: {
      'Content-Type': 'application/json',
      'Access-Control-Allow-Origin': '*',
    },
  });
}

function handleCors() {
  return new Response(null, {
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, X-API-Key',
      'Access-Control-Max-Age': '86400',
    },
  });
}

Using KV Store for Caching

KV Store is a global key-value database, perfect for caching API responses.

async function handleGetData(url, env) {
  const query = url.searchParams.get('q');
  if (!query) {
    return json({ error: 'Missing query parameter: q' }, 400);
  }

  // Check cache first
  const cacheKey = `data:${query}`;
  const cached = await env.CACHE.get(cacheKey, { type: 'json' });

  if (cached) {
    return json({ ...cached, cached: true });
  }

  // Generate or fetch data
  const result = await fetchExternalData(query);

  // Cache for 1 hour (3600 seconds)
  await env.CACHE.put(cacheKey, JSON.stringify(result), {
    expirationTtl: 3600,
  });

  return json({ ...result, cached: false });
}

async function handlePostData(request, env) {
  const body = await request.json();

  if (!body.name || !body.value) {
    return json({ error: 'Missing required fields: name, value' }, 400);
  }

  const id = crypto.randomUUID();
  const record = { id, ...body, createdAt: new Date().toISOString() };

  await env.CACHE.put(`record:${id}`, JSON.stringify(record));

  return json(record, 201);
}

Implementing Rate Limiting

Protect your API from abuse using a sliding window counter stored in KV:

async function rateLimit(request, env, limit = 60, window = 60) {
  const ip = request.headers.get('CF-Connecting-IP');
  const key = `ratelimit:${ip}`;

  const current = await env.CACHE.get(key, { type: 'json' });
  const now = Math.floor(Date.now() / 1000);

  if (current) {
    // Clean old entries outside the window
    const windowStart = now - window;
    const hits = current.timestamps.filter(t => t > windowStart);

    if (hits.length >= limit) {
      return {
        limited: true,
        response: json({
          error: 'Rate limit exceeded',
          retryAfter: window - (now - hits[0])
        }, 429)
      };
    }

    hits.push(now);
    await env.CACHE.put(key, JSON.stringify({ timestamps: hits }), {
      expirationTtl: window * 2,
    });
  } else {
    await env.CACHE.put(key, JSON.stringify({ timestamps: [now] }), {
      expirationTtl: window * 2,
    });
  }

  return { limited: false };
}

Integrate it into your main handler:

// Inside the fetch handler, before routing:
const { limited, response } = await rateLimit(request, env);
if (limited) return response;

Adding API Key Authentication

For APIs that need access control, implement API key validation:

function authenticate(request, env) {
  const apiKey = request.headers.get('X-API-Key');

  if (!apiKey) {
    return { authenticated: false, error: 'Missing X-API-Key header' };
  }

  // Store valid keys as a secret
  const validKeys = (env.API_KEYS || '').split(',');

  if (!validKeys.includes(apiKey)) {
    return { authenticated: false, error: 'Invalid API key' };
  }

  return { authenticated: true };
}

Set your API keys as secrets (never in wrangler.toml):

wrangler secret put API_KEYS
# Enter: key1,key2,key3

Apply authentication to protected routes:

if (path.startsWith('/api/admin')) {
  const auth = authenticate(request, env);
  if (!auth.authenticated) {
    return json({ error: auth.error }, 401);
  }
}

Local Development

Wrangler provides a local development server that simulates the Workers environment:

# Start local dev server
wrangler dev

# Test your endpoints
curl http://localhost:8787/api/health
curl -X POST http://localhost:8787/api/data \
  -H "Content-Type: application/json" \
  -d '{"name": "test", "value": 42}'

Deploying

One command to deploy globally:

wrangler deploy

Your API is now live at https://my-api.<your-subdomain>.workers.dev.

Custom Domain Setup

If your domain is on Cloudflare DNS, add a route in wrangler.toml:

routes = [
  { pattern = "api.yourdomain.com/*", zone_name = "yourdomain.com" }
]

Staying Within Free Tier Limits

Here are practical strategies to maximize the free tier:

Strategy	Impact
Cache aggressively with KV	Reduces external API calls
Use `Cache-Control` headers	Lets Cloudflare CDN handle repeat requests
Rate limit per IP	Prevents one user from burning your quota
Return early for invalid requests	Saves CPU time on bad input
Use `ctx.waitUntil()` for non-blocking writes	Keeps response times fast

// ctx.waitUntil example: log without blocking the response
ctx.waitUntil(
  env.CACHE.put(`log:${Date.now()}`, JSON.stringify({
    path: url.pathname,
    ip: request.headers.get('CF-Connecting-IP'),
    timestamp: new Date().toISOString()
  }))
);

return json({ data: result });

Production Checklist

Before going live, verify:

[ ] CORS headers configured for your frontend domain
[ ] Rate limiting enabled
[ ] Input validation on all POST/PUT endpoints
[ ] Secrets stored via wrangler secret, not in code
[ ] Error responses don't leak internal details
[ ] Cache TTLs set appropriately
[ ] Monitoring set up in Cloudflare dashboard

Wrapping Up

Cloudflare Workers is a powerful platform for building APIs with zero infrastructure cost. The combination of edge deployment, KV storage, and a generous free tier makes it ideal for developer tools, webhooks, and lightweight services.

If you want to see a real-world example of this approach, check out OG API - an open-source API built on Cloudflare Workers that generates Open Graph images dynamically, using the exact patterns covered in this guide.

What are you building with Cloudflare Workers? Share your projects in the comments!

Building Chrome Extensions in 2026: A Practical Guide with Manifest V3

Ryu0705 — Sun, 22 Mar 2026 14:31:08 +0000

Chrome extensions remain one of the most accessible ways to ship useful developer tools. With Manifest V3 now fully enforced, here's a practical guide to building extensions the right way in 2026.

Why Manifest V3?

Manifest V3 replaced the old V2 format with a focus on security, privacy, and performance. The key changes include:

Service workers instead of persistent background pages
Declarative net request instead of webRequest blocking
Tighter permissions with explicit host permissions

If you're starting a new extension today, V3 is the only option.

Project Structure

A typical Manifest V3 extension looks like this:

my-extension/
├── manifest.json
├── background.js        # Service worker
├── content.js           # Content script
├── popup/
│   ├── popup.html
│   └── popup.js
├── options/
│   ├── options.html
│   └── options.js
└── icons/
    ├── icon-16.png
    ├── icon-48.png
    └── icon-128.png

The Manifest File

Here's a minimal but complete manifest.json:

{
  "manifest_version": 3,
  "name": "My Developer Tool",
  "version": "1.0.0",
  "description": "A helpful developer tool",
  "permissions": ["storage", "activeTab"],
  "host_permissions": ["<all_urls>"],
  "background": {
    "service_worker": "background.js"
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["content.js"],
      "run_at": "document_idle"
    }
  ],
  "action": {
    "default_popup": "popup/popup.html",
    "default_icon": {
      "16": "icons/icon-16.png",
      "48": "icons/icon-48.png",
      "128": "icons/icon-128.png"
    }
  },
  "options_ui": {
    "page": "options/options.html",
    "open_in_tab": false
  }
}

Understanding the Core Components

Content Scripts: Interact with Web Pages

Content scripts run in the context of web pages. They can read and modify the DOM but live in an isolated JavaScript environment.

// content.js
// Detect JSON responses and format them
const body = document.body;
const text = body?.innerText;

if (isJsonContent(text)) {
  const parsed = JSON.parse(text);
  renderFormattedJson(parsed, body);
}

function isJsonContent(text) {
  try {
    JSON.parse(text);
    return document.contentType === 'application/json';
  } catch {
    return false;
  }
}

function renderFormattedJson(data, container) {
  const pre = document.createElement('pre');
  pre.textContent = JSON.stringify(data, null, 2);
  pre.style.cssText = 'font-family: monospace; padding: 16px;';
  container.innerHTML = '';
  container.appendChild(pre);
}

Popup: Quick Actions UI

The popup appears when users click your extension icon. Keep it focused and fast.

<!-- popup/popup.html -->
<!DOCTYPE html>
<html>
<head>
  <style>
    body { width: 300px; padding: 16px; font-family: system-ui; }
    .toggle { display: flex; justify-content: space-between; align-items: center; }
    button { padding: 8px 16px; cursor: pointer; }
  </style>
</head>
<body>
  <h3>My Developer Tool</h3>
  <div class="toggle">
    <span>Enable formatting</span>
    <button id="toggleBtn">ON</button>
  </div>
  <script src="popup.js"></script>
</body>
</html>

// popup/popup.js
const btn = document.getElementById('toggleBtn');

// Load saved state
chrome.storage.sync.get(['enabled'], (result) => {
  const enabled = result.enabled !== false;
  btn.textContent = enabled ? 'ON' : 'OFF';
});

// Toggle on click
btn.addEventListener('click', () => {
  chrome.storage.sync.get(['enabled'], (result) => {
    const newState = result.enabled === false;
    chrome.storage.sync.set({ enabled: newState });
    btn.textContent = newState ? 'ON' : 'OFF';
  });
});

Options Page: User Preferences

The options page lets users configure your extension. It opens from chrome://extensions or right-clicking the extension icon.

// options/options.js
const themeSelect = document.getElementById('theme');
const indentInput = document.getElementById('indent');

// Load preferences
chrome.storage.sync.get(['theme', 'indent'], (result) => {
  themeSelect.value = result.theme || 'dark';
  indentInput.value = result.indent || 2;
});

// Save on change
document.getElementById('save').addEventListener('click', () => {
  chrome.storage.sync.set({
    theme: themeSelect.value,
    indent: parseInt(indentInput.value, 10)
  });
});

Service Worker: Background Logic

The service worker handles events, manages state, and coordinates between components.

// background.js
chrome.runtime.onInstalled.addListener((details) => {
  if (details.reason === 'install') {
    chrome.storage.sync.set({ enabled: true, theme: 'dark', indent: 2 });
  }
});

// Listen for messages from content scripts
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === 'GET_SETTINGS') {
    chrome.storage.sync.get(['enabled', 'theme', 'indent'], (settings) => {
      sendResponse(settings);
    });
    return true; // Keep channel open for async response
  }
});

Permission Minimization Best Practices

One of V3's goals is reducing excessive permissions. Follow these rules:

1. Use activeTab instead of broad host permissions when possible

// Bad: Requests access to all sites on install
"host_permissions": ["<all_urls>"]

// Good: Only activates when user clicks the extension
"permissions": ["activeTab"]

2. Request optional permissions at runtime

// Request permissions only when needed
chrome.permissions.request(
  { origins: ['https://api.example.com/*'] },
  (granted) => {
    if (granted) {
      fetchData();
    }
  }
);

3. Only declare what you use

Every permission you list appears in the Chrome Web Store listing. Users are more likely to install extensions with fewer permissions.

Permission	Use When
`storage`	Saving user preferences
`activeTab`	Accessing the current tab on click
`tabs`	Reading tab URLs (consider if you really need this)
`alarms`	Scheduling periodic tasks

Debugging and Testing

Loading Your Extension

Open chrome://extensions
Enable Developer mode (top right)
Click Load unpacked and select your project folder
Your extension appears in the toolbar

Debugging Tips

Service worker logs: Click "Inspect views: service worker" on the extensions page.

Content script logs: Open DevTools on any page where your content script runs. Logs appear in the regular console.

Popup debugging: Right-click your extension icon, click "Inspect popup". This opens DevTools for the popup context.

Testing Strategy

// Use a simple test runner for unit tests
// test/format.test.js
import { describe, it, expect } from 'vitest';
import { isJsonContent, formatJson } from '../src/utils.js';

describe('JSON detection', () => {
  it('detects valid JSON strings', () => {
    expect(isJsonContent('{"key": "value"}')).toBe(true);
  });

  it('rejects invalid JSON', () => {
    expect(isJsonContent('not json')).toBe(false);
  });
});

describe('JSON formatting', () => {
  it('formats with custom indent', () => {
    const input = '{"a":1}';
    const result = formatJson(input, 4);
    expect(result).toContain('    "a"');
  });
});

For end-to-end testing, use Puppeteer with extension support:

const browser = await puppeteer.launch({
  headless: false,
  args: [
    `--disable-extensions-except=${extensionPath}`,
    `--load-extension=${extensionPath}`
  ]
});

Common Pitfalls

Service worker lifecycle: Unlike background pages, service workers terminate when idle. Don't store state in global variables; use chrome.storage instead.
Content Security Policy: V3 disallows inline scripts in extension pages. Move all JavaScript to separate files.
Message passing: Always return true from onMessage listeners if you call sendResponse asynchronously.

Wrapping Up

Manifest V3 enforces better security patterns that ultimately lead to better extensions. Start with minimal permissions, use the component model (content script, popup, options, service worker) to separate concerns, and test early.

If you want to see these patterns in action, check out JSON Formatter Pro - an open-source Chrome extension that auto-detects and beautifully formats JSON in your browser, built with all the Manifest V3 best practices covered in this guide.

Have questions about Chrome extension development? Drop them in the comments!

How to Build a Free API with Cloudflare Workers (Zero Infrastructure Cost)

Ryu0705 — Sun, 22 Mar 2026 14:23:35 +0000

What You Get for Free

Cloudflare Workers free tier includes:

100,000 requests/day
10ms CPU time per request (enough for most APIs)
KV Storage: 100,000 reads/day, 1,000 writes/day
Global deployment across 300+ data centers
Custom domains via Cloudflare DNS

For personal projects, internal tools, and moderate-traffic APIs, this is more than enough.

Setting Up

Install Wrangler

Wrangler is Cloudflare's CLI for Workers development.

npm install -g wrangler
wrangler login

Create a New Project

wrangler init my-api
cd my-api

This generates a basic project with wrangler.toml and src/index.js.

Configure wrangler.toml

name = "my-api"
main = "src/index.js"
compatibility_date = "2026-03-01"

[vars]
API_VERSION = "1.0.0"

[[kv_namespaces]]
binding = "CACHE"
id = "your-kv-namespace-id"

Create the KV namespace:

wrangler kv namespace create CACHE
# Copy the output id into wrangler.toml

Building the Router

Workers receive a fetch event. Here's a clean routing pattern without any external dependencies:

// src/index.js
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    const path = url.pathname;
    const method = request.method;

    // CORS headers
    if (method === 'OPTIONS') {
      return handleCors();
    }

    try {
      // Route matching
      if (path === '/api/health' && method === 'GET') {
        return json({ status: 'ok', version: env.API_VERSION });
      }

      if (path === '/api/data' && method === 'GET') {
        return await handleGetData(url, env);
      }

      if (path === '/api/data' && method === 'POST') {
        return await handlePostData(request, env);
      }

      return json({ error: 'Not found' }, 404);
    } catch (err) {
      return json({ error: 'Internal server error' }, 500);
    }
  }
};

function json(data, status = 200) {
  return new Response(JSON.stringify(data), {
    status,
    headers: {
      'Content-Type': 'application/json',
      'Access-Control-Allow-Origin': '*',
    },
  });
}

function handleCors() {
  return new Response(null, {
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, X-API-Key',
      'Access-Control-Max-Age': '86400',
    },
  });
}

Using KV Store for Caching

KV Store is a global key-value database, perfect for caching API responses.

async function handleGetData(url, env) {
  const query = url.searchParams.get('q');
  if (!query) {
    return json({ error: 'Missing query parameter: q' }, 400);
  }

  // Check cache first
  const cacheKey = `data:${query}`;
  const cached = await env.CACHE.get(cacheKey, { type: 'json' });

  if (cached) {
    return json({ ...cached, cached: true });
  }

  // Generate or fetch data
  const result = await fetchExternalData(query);

  // Cache for 1 hour (3600 seconds)
  await env.CACHE.put(cacheKey, JSON.stringify(result), {
    expirationTtl: 3600,
  });

  return json({ ...result, cached: false });
}

async function handlePostData(request, env) {
  const body = await request.json();

  if (!body.name || !body.value) {
    return json({ error: 'Missing required fields: name, value' }, 400);
  }

  const id = crypto.randomUUID();
  const record = { id, ...body, createdAt: new Date().toISOString() };

  await env.CACHE.put(`record:${id}`, JSON.stringify(record));

  return json(record, 201);
}

Implementing Rate Limiting

Protect your API from abuse using a sliding window counter stored in KV:

async function rateLimit(request, env, limit = 60, window = 60) {
  const ip = request.headers.get('CF-Connecting-IP');
  const key = `ratelimit:${ip}`;

  const current = await env.CACHE.get(key, { type: 'json' });
  const now = Math.floor(Date.now() / 1000);

  if (current) {
    // Clean old entries outside the window
    const windowStart = now - window;
    const hits = current.timestamps.filter(t => t > windowStart);

    if (hits.length >= limit) {
      return {
        limited: true,
        response: json({
          error: 'Rate limit exceeded',
          retryAfter: window - (now - hits[0])
        }, 429)
      };
    }

    hits.push(now);
    await env.CACHE.put(key, JSON.stringify({ timestamps: hits }), {
      expirationTtl: window * 2,
    });
  } else {
    await env.CACHE.put(key, JSON.stringify({ timestamps: [now] }), {
      expirationTtl: window * 2,
    });
  }

  return { limited: false };
}

Integrate it into your main handler:

// Inside the fetch handler, before routing:
const { limited, response } = await rateLimit(request, env);
if (limited) return response;

Adding API Key Authentication

For APIs that need access control, implement API key validation:

function authenticate(request, env) {
  const apiKey = request.headers.get('X-API-Key');

  if (!apiKey) {
    return { authenticated: false, error: 'Missing X-API-Key header' };
  }

  // Store valid keys as a secret
  const validKeys = (env.API_KEYS || '').split(',');

  if (!validKeys.includes(apiKey)) {
    return { authenticated: false, error: 'Invalid API key' };
  }

  return { authenticated: true };
}

Set your API keys as secrets (never in wrangler.toml):

wrangler secret put API_KEYS
# Enter: key1,key2,key3

Apply authentication to protected routes:

if (path.startsWith('/api/admin')) {
  const auth = authenticate(request, env);
  if (!auth.authenticated) {
    return json({ error: auth.error }, 401);
  }
}

Local Development

Wrangler provides a local development server that simulates the Workers environment:

# Start local dev server
wrangler dev

# Test your endpoints
curl http://localhost:8787/api/health
curl -X POST http://localhost:8787/api/data \
  -H "Content-Type: application/json" \
  -d '{"name": "test", "value": 42}'

Deploying

One command to deploy globally:

wrangler deploy

Your API is now live at https://my-api.<your-subdomain>.workers.dev.

Custom Domain Setup

If your domain is on Cloudflare DNS, add a route in wrangler.toml:

routes = [
  { pattern = "api.yourdomain.com/*", zone_name = "yourdomain.com" }
]

Staying Within Free Tier Limits

Here are practical strategies to maximize the free tier:

Strategy	Impact
Cache aggressively with KV	Reduces external API calls
Use `Cache-Control` headers	Lets Cloudflare CDN handle repeat requests
Rate limit per IP	Prevents one user from burning your quota
Return early for invalid requests	Saves CPU time on bad input
Use `ctx.waitUntil()` for non-blocking writes	Keeps response times fast

// ctx.waitUntil example: log without blocking the response
ctx.waitUntil(
  env.CACHE.put(`log:${Date.now()}`, JSON.stringify({
    path: url.pathname,
    ip: request.headers.get('CF-Connecting-IP'),
    timestamp: new Date().toISOString()
  }))
);

return json({ data: result });

Production Checklist

Before going live, verify:

[ ] CORS headers configured for your frontend domain
[ ] Rate limiting enabled
[ ] Input validation on all POST/PUT endpoints
[ ] Secrets stored via wrangler secret, not in code
[ ] Error responses don't leak internal details
[ ] Cache TTLs set appropriately
[ ] Monitoring set up in Cloudflare dashboard

Wrapping Up

What are you building with Cloudflare Workers? Share your projects in the comments!

Building Chrome Extensions in 2026: A Practical Guide with Manifest V3

Ryu0705 — Sun, 22 Mar 2026 14:21:13 +0000

Chrome extensions remain one of the most accessible ways to ship useful developer tools. With Manifest V3 now fully enforced, here's a practical guide to building extensions the right way in 2026.

Why Manifest V3?

Manifest V3 replaced the old V2 format with a focus on security, privacy, and performance. The key changes include:

Service workers instead of persistent background pages
Declarative net request instead of webRequest blocking
Tighter permissions with explicit host permissions

If you're starting a new extension today, V3 is the only option.

Project Structure

A typical Manifest V3 extension looks like this:

my-extension/
├── manifest.json
├── background.js        # Service worker
├── content.js           # Content script
├── popup/
│   ├── popup.html
│   └── popup.js
├── options/
│   ├── options.html
│   └── options.js
└── icons/
    ├── icon-16.png
    ├── icon-48.png
    └── icon-128.png

The Manifest File

Here's a minimal but complete manifest.json:

{
  "manifest_version": 3,
  "name": "My Developer Tool",
  "version": "1.0.0",
  "description": "A helpful developer tool",
  "permissions": ["storage", "activeTab"],
  "host_permissions": ["<all_urls>"],
  "background": {
    "service_worker": "background.js"
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["content.js"],
      "run_at": "document_idle"
    }
  ],
  "action": {
    "default_popup": "popup/popup.html",
    "default_icon": {
      "16": "icons/icon-16.png",
      "48": "icons/icon-48.png",
      "128": "icons/icon-128.png"
    }
  },
  "options_ui": {
    "page": "options/options.html",
    "open_in_tab": false
  }
}

Understanding the Core Components

Content Scripts: Interact with Web Pages

Content scripts run in the context of web pages. They can read and modify the DOM but live in an isolated JavaScript environment.

// content.js
// Detect JSON responses and format them
const body = document.body;
const text = body?.innerText;

if (isJsonContent(text)) {
  const parsed = JSON.parse(text);
  renderFormattedJson(parsed, body);
}

function isJsonContent(text) {
  try {
    JSON.parse(text);
    return document.contentType === 'application/json';
  } catch {
    return false;
  }
}

function renderFormattedJson(data, container) {
  const pre = document.createElement('pre');
  pre.textContent = JSON.stringify(data, null, 2);
  pre.style.cssText = 'font-family: monospace; padding: 16px;';
  container.innerHTML = '';
  container.appendChild(pre);
}

Popup: Quick Actions UI

The popup appears when users click your extension icon. Keep it focused and fast.

<!-- popup/popup.html -->
<!DOCTYPE html>
<html>
<head>
  <style>
    body { width: 300px; padding: 16px; font-family: system-ui; }
    .toggle { display: flex; justify-content: space-between; align-items: center; }
    button { padding: 8px 16px; cursor: pointer; }
  </style>
</head>
<body>
  <h3>My Developer Tool</h3>
  <div class="toggle">
    <span>Enable formatting</span>
    <button id="toggleBtn">ON</button>
  </div>
  <script src="popup.js"></script>
</body>
</html>

// popup/popup.js
const btn = document.getElementById('toggleBtn');

// Load saved state
chrome.storage.sync.get(['enabled'], (result) => {
  const enabled = result.enabled !== false;
  btn.textContent = enabled ? 'ON' : 'OFF';
});

// Toggle on click
btn.addEventListener('click', () => {
  chrome.storage.sync.get(['enabled'], (result) => {
    const newState = result.enabled === false;
    chrome.storage.sync.set({ enabled: newState });
    btn.textContent = newState ? 'ON' : 'OFF';
  });
});

Options Page: User Preferences

The options page lets users configure your extension. It opens from chrome://extensions or right-clicking the extension icon.

// options/options.js
const themeSelect = document.getElementById('theme');
const indentInput = document.getElementById('indent');

// Load preferences
chrome.storage.sync.get(['theme', 'indent'], (result) => {
  themeSelect.value = result.theme || 'dark';
  indentInput.value = result.indent || 2;
});

// Save on change
document.getElementById('save').addEventListener('click', () => {
  chrome.storage.sync.set({
    theme: themeSelect.value,
    indent: parseInt(indentInput.value, 10)
  });
});

Service Worker: Background Logic

The service worker handles events, manages state, and coordinates between components.

// background.js
chrome.runtime.onInstalled.addListener((details) => {
  if (details.reason === 'install') {
    chrome.storage.sync.set({ enabled: true, theme: 'dark', indent: 2 });
  }
});

// Listen for messages from content scripts
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === 'GET_SETTINGS') {
    chrome.storage.sync.get(['enabled', 'theme', 'indent'], (settings) => {
      sendResponse(settings);
    });
    return true; // Keep channel open for async response
  }
});

Permission Minimization Best Practices

One of V3's goals is reducing excessive permissions. Follow these rules:

1. Use activeTab instead of broad host permissions when possible

// Bad: Requests access to all sites on install
"host_permissions": ["<all_urls>"]

// Good: Only activates when user clicks the extension
"permissions": ["activeTab"]

2. Request optional permissions at runtime

// Request permissions only when needed
chrome.permissions.request(
  { origins: ['https://api.example.com/*'] },
  (granted) => {
    if (granted) {
      fetchData();
    }
  }
);

3. Only declare what you use

Every permission you list appears in the Chrome Web Store listing. Users are more likely to install extensions with fewer permissions.

Permission	Use When
`storage`	Saving user preferences
`activeTab`	Accessing the current tab on click
`tabs`	Reading tab URLs (consider if you really need this)
`alarms`	Scheduling periodic tasks

Debugging and Testing

Loading Your Extension

Open chrome://extensions
Enable Developer mode (top right)
Click Load unpacked and select your project folder
Your extension appears in the toolbar

Debugging Tips

Service worker logs: Click "Inspect views: service worker" on the extensions page.

Content script logs: Open DevTools on any page where your content script runs. Logs appear in the regular console.

Popup debugging: Right-click your extension icon, click "Inspect popup". This opens DevTools for the popup context.

Testing Strategy

// Use a simple test runner for unit tests
// test/format.test.js
import { describe, it, expect } from 'vitest';
import { isJsonContent, formatJson } from '../src/utils.js';

describe('JSON detection', () => {
  it('detects valid JSON strings', () => {
    expect(isJsonContent('{"key": "value"}')).toBe(true);
  });

  it('rejects invalid JSON', () => {
    expect(isJsonContent('not json')).toBe(false);
  });
});

describe('JSON formatting', () => {
  it('formats with custom indent', () => {
    const input = '{"a":1}';
    const result = formatJson(input, 4);
    expect(result).toContain('    "a"');
  });
});

For end-to-end testing, use Puppeteer with extension support:

const browser = await puppeteer.launch({
  headless: false,
  args: [
    `--disable-extensions-except=${extensionPath}`,
    `--load-extension=${extensionPath}`
  ]
});

Common Pitfalls

Service worker lifecycle: Unlike background pages, service workers terminate when idle. Don't store state in global variables; use chrome.storage instead.
Content Security Policy: V3 disallows inline scripts in extension pages. Move all JavaScript to separate files.
Message passing: Always return true from onMessage listeners if you call sendResponse asynchronously.

Wrapping Up

Have questions about Chrome extension development? Drop them in the comments!

Security Vulnerabilities Every Developer Should Know (OWASP Top 10 Simplified)

Ryu0705 — Sun, 22 Mar 2026 11:39:23 +0000

Most developers know they should "write secure code." But when asked what that means specifically, the answer gets vague fast.

The OWASP Top 10 is the industry standard list of critical web application security risks. But the official documentation is dense and aimed at security professionals. This guide translates each vulnerability into vulnerable code vs. fixed code examples that any developer can understand and act on.

A01: Broken Access Control

The problem: Users can act outside their intended permissions — viewing other users' data, modifying records they don't own, or escalating privileges.

This is the #1 vulnerability on the OWASP list, and it's surprisingly common.

// VULNERABLE: Any authenticated user can view any profile
app.get('/api/users/:id', auth, (req, res) => {
  const user = db.getUser(req.params.id);
  res.json(user);
});

// FIXED: Verify resource ownership
app.get('/api/users/:id', auth, (req, res) => {
  if (req.user.id !== req.params.id && !req.user.isAdmin) {
    return res.status(403).json({ error: 'Forbidden' });
  }
  const user = db.getUser(req.params.id);
  res.json(user);
});

Checklist:

[ ] Every endpoint checks authorization (not just authentication)
[ ] Resource ownership is verified before access
[ ] CORS is configured restrictively (never * in production)
[ ] CSRF tokens protect state-changing operations
[ ] No path traversal in file operations (../)

A02: Cryptographic Failures

The problem: Sensitive data is exposed through weak cryptography, missing encryption, or accidental leakage.

# VULNERABLE: MD5 for password hashing
import hashlib
password_hash = hashlib.md5(password.encode()).hexdigest()

# FIXED: Use bcrypt with auto-generated salt
import bcrypt
password_hash = bcrypt.hashpw(password.encode(), bcrypt.gensalt())

Checklist:

[ ] Passwords hashed with bcrypt or argon2 (never MD5/SHA)
[ ] No hardcoded secrets or API keys in source code
[ ] Sensitive data not logged or in URL parameters
[ ] HTTPS enforced for all data transmission
[ ] PII encrypted at rest in the database

A03: Injection

The problem: Untrusted data is sent to an interpreter as part of a command or query. SQL injection is the classic example, but it extends to OS commands, LDAP, and more.

// VULNERABLE: SQL injection via string interpolation
const query = `SELECT * FROM users WHERE email = '${email}'`;
db.query(query);
// Attacker input: ' OR 1=1 --
// Resulting query: SELECT * FROM users WHERE email = '' OR 1=1 --'

// FIXED: Parameterized query
const query = 'SELECT * FROM users WHERE email = $1';
db.query(query, [email]);

// VULNERABLE: Command injection
const { exec } = require('child_process');
exec(`convert ${userFilename} output.png`); // userFilename = "; rm -rf /"

// FIXED: Use array-based API that doesn't invoke shell
const { execFile } = require('child_process');
execFile('convert', [userFilename, 'output.png']);

Checklist:

[ ] All SQL uses parameterized queries or ORM
[ ] No eval() or new Function() with user input
[ ] No shell execution with user-controlled strings
[ ] No innerHTML / dangerouslySetInnerHTML with user data
[ ] NoSQL queries don't pass user input to $where or $regex

A04: Insecure Design

The problem: Security flaws baked into the architecture itself, not just the implementation. No amount of good code fixes a bad design.

Example: A password reset flow that sends a reset link to the email address provided in the request (instead of the email on file).

Checklist:

[ ] Rate limiting on authentication endpoints
[ ] Account lockout after failed login attempts
[ ] Password reset uses the email on file, not user input
[ ] Business logic validated server-side (never trust the client)
[ ] Threat modeling done for sensitive features

A05: Security Misconfiguration

The problem: Insecure default settings, incomplete configurations, or unnecessary features left enabled.

// VULNERABLE: Express app in production
app.use(express.errorHandler()); // Exposes stack traces

// FIXED: Custom error handler for production
app.use((err, req, res, next) => {
  console.error(err); // Log internally
  res.status(500).json({ 
    error: 'Internal server error' // Don't leak details
  });
});

Checklist:

[ ] Debug mode disabled in production
[ ] Default credentials changed everywhere
[ ] Security headers configured (CSP, HSTS, X-Frame-Options)
[ ] Error messages don't expose stack traces or internals
[ ] Directory listing disabled
[ ] Unnecessary features and endpoints removed

A06: Vulnerable and Outdated Components

The problem: Using libraries or frameworks with known security vulnerabilities.

# Check your project right now
npm audit
# or
pip install safety && safety check

Checklist:

[ ] npm audit / pip audit runs in CI pipeline
[ ] Dependencies updated regularly
[ ] No abandoned packages (2+ years without updates)
[ ] Lock files committed to version control

A07: Identification and Authentication Failures

The problem: Weaknesses in authentication that allow attackers to compromise passwords, sessions, or tokens.

// VULNERABLE: Session not invalidated on logout
app.post('/logout', (req, res) => {
  res.clearCookie('session'); // Only clears client-side!
  res.redirect('/login');
});

// FIXED: Destroy server-side session
app.post('/logout', (req, res) => {
  req.session.destroy((err) => {
    res.clearCookie('session');
    res.redirect('/login');
  });
});

Checklist:

[ ] Strong password requirements enforced
[ ] Sessions invalidated server-side on logout
[ ] Session IDs never exposed in URLs
[ ] MFA available for sensitive operations
[ ] Credential stuffing mitigated with rate limiting

A08: Software and Data Integrity Failures

The problem: Code or data that is used without verifying its integrity.

<!-- VULNERABLE: CDN resource without integrity check -->
<script src=\"https://cdn.example.com/lib.js\"></script>

<!-- FIXED: Subresource Integrity (SRI) -->
<script src=\"https://cdn.example.com/lib.js\" 
        integrity=\"sha384-abc123...\" 
        crossorigin=\"anonymous\"></script>

Checklist:

[ ] CDN resources use Subresource Integrity (SRI)
[ ] No deserialization of untrusted data
[ ] CI/CD pipeline has integrity checks
[ ] Auto-updates verify signatures

A09: Security Logging and Monitoring Failures

The problem: Without proper logging, breaches go undetected — the average time to detect a breach is 287 days.

Checklist:

[ ] Login attempts (success and failure) are logged
[ ] Access control failures are logged
[ ] Sensitive data is NEVER in logs (passwords, tokens, PII)
[ ] Alerts configured for suspicious activity patterns
[ ] Logs are tamper-protected

A10: Server-Side Request Forgery (SSRF)

The problem: The application fetches a remote resource using a user-supplied URL without validation, allowing attackers to reach internal services.

// VULNERABLE: User controls the fetch URL
app.get('/preview', async (req, res) => {
  const response = await fetch(req.query.url);
  res.send(await response.text());
});
// Attacker: /preview?url=http://169.254.169.254/metadata
// (AWS metadata endpoint - leaks credentials)

// FIXED: Allowlist validation
const ALLOWED_HOSTS = ['api.example.com', 'cdn.example.com'];
app.get('/preview', async (req, res) => {
  const url = new URL(req.query.url);
  if (!ALLOWED_HOSTS.includes(url.hostname)) {
    return res.status(400).json({ error: 'Host not allowed' });
  }
  const response = await fetch(url.toString());
  res.send(await response.text());
});

Checklist:

[ ] User-supplied URLs validated against an allowlist
[ ] Internal network addresses blocked (10.x, 172.16.x, 169.254.x)
[ ] DNS rebinding prevention in place
[ ] Outbound requests have firewall rules

The Complete Security Checklist

Here's the consolidated quick-reference:

Category	Key Rule
Access Control	Verify ownership, not just authentication
Cryptography	bcrypt for passwords, no hardcoded secrets
Injection	Parameterize everything, never concatenate
Design	Rate limit, validate server-side
Configuration	No debug in prod, set security headers
Dependencies	Audit regularly, update promptly
Authentication	Destroy sessions server-side, enforce MFA
Integrity	SRI for CDN, verify signatures
Logging	Log auth events, never log secrets
SSRF	Allowlist outbound URLs

Making Security Automatic

Manual security review is important but insufficient. I built Security Audit Pro — a Claude Code skill that automatically scans your codebase against OWASP Top 10 rules, CWE Top 25, dependency vulnerabilities, and secrets detection. It produces a prioritized report with specific line-level findings and fix suggestions.

Whether you use automated tools or this manual checklist, building security into your regular review process is what matters. Don't wait for a breach to start caring about security.

Which of these vulnerabilities have you encountered in your own codebase? I'd bet at least 3 of these 10 apply to most production applications right now.

The Edge Cases Your Tests Are Missing: A Pattern Library

Ryu0705 — Sun, 22 Mar 2026 11:38:09 +0000

You wrote tests. They pass. Coverage looks good. You ship to production and... it breaks.

The problem isn't that you didn't write tests — it's that you tested the expected inputs while your users sent the unexpected ones.

After cataloguing hundreds of production bugs, I've built a pattern library of edge cases that most test suites miss. Here's the collection, organized by type, with concrete examples you can apply today.

The Null/Undefined/Empty Family

This is the #1 source of production errors. For every function that accepts input, ask: "What if it's empty?"

// Your function
function getFullName(user) {
  return `${user.firstName} ${user.lastName}`;
}

// Tests you probably wrote
test('returns full name', () => {
  expect(getFullName({ firstName: 'Jane', lastName: 'Doe' }))
    .toBe('Jane Doe');
});

// Tests you probably DIDN'T write
test('handles null input', () => {
  expect(() => getFullName(null)).toThrow();
});

test('handles missing fields', () => {
  expect(getFullName({ firstName: 'Jane' }))
    .toBe('Jane undefined'); // Is this what you want?
});

test('handles empty strings', () => {
  expect(getFullName({ firstName: '', lastName: '' }))
    .toBe(' '); // A single space? Really?
});

The full "empty" family to test:

null
undefined
"" (empty string)
" " (whitespace-only string)
[] (empty array)
{} (empty object)
0 (zero — falsy but valid!)

The Dangerous Numbers

Numbers have more edge cases than most developers realize. JavaScript makes this especially tricky.

function calculateDiscount(price, percentage) {
  return price * (percentage / 100);
}

// Are you testing these?
test('handles zero price', () => {
  expect(calculateDiscount(0, 50)).toBe(0);
});

test('handles floating point precision', () => {
  // 0.1 + 0.2 !== 0.3 in JavaScript
  expect(calculateDiscount(10, 33.3))
    .toBeCloseTo(3.33); // NOT toBe!
});

test('handles negative numbers', () => {
  expect(calculateDiscount(-100, 50)).toBe(-50);
  // Is a negative discount valid in your business logic?
});

test('handles percentage over 100', () => {
  expect(calculateDiscount(100, 150)).toBe(150);
  // Should this be allowed?
});

test('handles NaN', () => {
  expect(calculateDiscount(NaN, 50)).toBeNaN();
  // What should actually happen here?
});

The dangerous numbers checklist:

0 and -0 (yes, negative zero exists)
NaN, Infinity, -Infinity
Number.MAX_SAFE_INTEGER (9007199254740991)
Floating point: 0.1 + 0.2 (use toBeCloseTo)
Negative numbers where only positive expected

Strings That Break Things

Strings are deceptively complex. Unicode, special characters, and encoding issues cause some of the most confusing bugs.

function slugify(title) {
  return title.toLowerCase().replace(/\s+/g, '-');
}

// Beyond the happy path, test these:
const edgeCases = [
  ['', ''],                          // empty
  ['a', 'a'],                        // single char
  ['Hello World', 'hello-world'],    // normal
  ['  spaces  ', '--spaces--'],      // leading/trailing
  ['emoji \ud83d\ude80 test', 'emoji-\ud83d\ude80-test'], // unicode
  ['<script>alert(1)</script>', '<script>alert(1)</script>'], // XSS
  ['a'.repeat(10000), /* ? */],      // very long
  ['\t\n\r', '---'],                 // whitespace chars
];

Strings to always test:

Empty string and whitespace-only
Single character
Very long strings (10,000+ characters)
Unicode: emoji, CJK characters, RTL text
Special chars: <, >, &, ", ', \, /
Injection patterns: ' OR 1=1 -- and <script>
Null bytes, newlines, tabs

Boundary Values: The Off-by-One Epidemic

The principle is simple: test at min, min+1, typical, max-1, max. Yet most test suites only test "typical."

function paginate(items, page, pageSize = 10) {
  const start = (page - 1) * pageSize;
  return items.slice(start, start + pageSize);
}

// Boundary tests
test('page 0 (invalid)', () => {
  expect(paginate(items, 0)).toEqual([]); // Or should it throw?
});

test('page 1 (first page)', () => {
  expect(paginate(items, 1)).toHaveLength(10);
});

test('last page with exact fit', () => {
  const items = Array.from({ length: 30 }, (_, i) => i);
  expect(paginate(items, 3)).toHaveLength(10);
});

test('last page with partial results', () => {
  const items = Array.from({ length: 25 }, (_, i) => i);
  expect(paginate(items, 3)).toHaveLength(5);
});

test('page beyond total pages', () => {
  const items = Array.from({ length: 5 }, (_, i) => i);
  expect(paginate(items, 100)).toEqual([]);
});

test('pageSize of 1', () => {
  expect(paginate(items, 1, 1)).toHaveLength(1);
});

test('pageSize of 0', () => {
  expect(paginate(items, 1, 0)).toEqual([]); // Or throw?
});

Common boundary categories:

Pagination: page 0, 1, last, beyond-last
Counts: 0 items, 1 item, exactly-at-limit, limit+1
Money: $0.00, $0.01, sub-cent amounts ($0.001)
Dates: midnight, end-of-day, leap year Feb 29, DST transitions
String lengths: 0, 1, at-validation-limit, one-over-limit

Async Errors: The Silent Killers

Async code multiplies edge cases. Network failures, timeouts, and race conditions are hard to reproduce in tests but common in production.

// Testing async error paths
test('handles network timeout', async () => {
  jest.spyOn(global, 'fetch').mockImplementation(
    () => new Promise((_, reject) => 
      setTimeout(() => reject(new Error('Timeout')), 100)
    )
  );

  await expect(fetchUserData(1)).rejects.toThrow('Timeout');
});

test('handles empty response body', async () => {
  jest.spyOn(global, 'fetch').mockResolvedValue({
    ok: true,
    json: () => Promise.reject(new SyntaxError('Unexpected end of JSON'))
  });

  await expect(fetchUserData(1)).rejects.toThrow();
});

test('handles concurrent calls gracefully', async () => {
  // Fire 10 simultaneous requests
  const promises = Array.from({ length: 10 }, 
    (_, i) => fetchUserData(i)
  );

  // None should throw unhandled rejections
  const results = await Promise.allSettled(promises);
  expect(results.some(r => r.status === 'fulfilled')).toBe(true);
});

Async edge cases to cover:

Connection timeout vs. read timeout
HTTP 4xx and 5xx responses (each separately!)
Empty or malformed response body
Concurrent calls to the same resource
Retry after failure (does it actually retry?)
Partial failure in batch operations

The Quick Reference Checklist

For every function you write, run through this mental checklist:

Input Type	Edge Cases to Test
Any parameter	null, undefined
Strings	empty, whitespace, very long, special chars, unicode
Numbers	0, negative, NaN, Infinity, float precision
Arrays	empty, single item, duplicates, very large
Objects	empty, missing fields, extra fields, circular refs
Dates	midnight, leap year, DST, timezone boundaries
Async	timeout, network error, empty response, concurrent
Files	not found, permission denied, empty, very large

Building This Into Your Workflow

You don't need to memorize all of this. I built Test Forge — a Claude Code skill that automatically generates edge case tests from your source code. It analyzes your functions, identifies untested edge cases from the pattern library above, and generates ready-to-run test code.

Whether you use a tool or this reference guide, the key is shifting from "does my code work?" to "how can my code break?" That mindset shift alone will cut your production bugs in half.

What's the weirdest edge case bug you've encountered in production? I'd love to hear your war stories in the comments.

The Edge Cases Your Tests Are Missing: A Pattern Library

Ryu0705 — Sun, 22 Mar 2026 11:31:55 +0000

You wrote tests. They pass. Coverage looks good. You ship to production and... it breaks.

The problem isn't that you didn't write tests — it's that you tested the expected inputs while your users sent the unexpected ones.

The Null/Undefined/Empty Family

This is the #1 source of production errors. For every function that accepts input, ask: "What if it's empty?"

// Your function
function getFullName(user) {
  return `${user.firstName} ${user.lastName}`;
}

// Tests you probably wrote
test('returns full name', () => {
  expect(getFullName({ firstName: 'Jane', lastName: 'Doe' }))
    .toBe('Jane Doe');
});

// Tests you probably DIDN'T write
test('handles null input', () => {
  expect(() => getFullName(null)).toThrow();
});

test('handles missing fields', () => {
  expect(getFullName({ firstName: 'Jane' }))
    .toBe('Jane undefined'); // Is this what you want?
});

test('handles empty strings', () => {
  expect(getFullName({ firstName: '', lastName: '' }))
    .toBe(' '); // A single space? Really?
});

The full "empty" family to test:

null
undefined
"" (empty string)
" " (whitespace-only string)
[] (empty array)
{} (empty object)
0 (zero — falsy but valid!)

The Dangerous Numbers

Numbers have more edge cases than most developers realize. JavaScript makes this especially tricky.

function calculateDiscount(price, percentage) {
  return price * (percentage / 100);
}

// Are you testing these?
test('handles zero price', () => {
  expect(calculateDiscount(0, 50)).toBe(0);
});

test('handles floating point precision', () => {
  // 0.1 + 0.2 !== 0.3 in JavaScript
  expect(calculateDiscount(10, 33.3))
    .toBeCloseTo(3.33); // NOT toBe!
});

test('handles negative numbers', () => {
  expect(calculateDiscount(-100, 50)).toBe(-50);
  // Is a negative discount valid in your business logic?
});

test('handles percentage over 100', () => {
  expect(calculateDiscount(100, 150)).toBe(150);
  // Should this be allowed?
});

test('handles NaN', () => {
  expect(calculateDiscount(NaN, 50)).toBeNaN();
  // What should actually happen here?
});

The dangerous numbers checklist:

0 and -0 (yes, negative zero exists)
NaN, Infinity, -Infinity
Number.MAX_SAFE_INTEGER (9007199254740991)
Floating point: 0.1 + 0.2 (use toBeCloseTo)
Negative numbers where only positive expected

Strings That Break Things

Strings are deceptively complex. Unicode, special characters, and encoding issues cause some of the most confusing bugs.

function slugify(title) {
  return title.toLowerCase().replace(/\s+/g, '-');
}

// Beyond the happy path, test these:
const edgeCases = [
  ['', ''],                          // empty
  ['a', 'a'],                        // single char
  ['Hello World', 'hello-world'],    // normal
  ['  spaces  ', '--spaces--'],      // leading/trailing
  ['emoji \ud83d\ude80 test', 'emoji-\ud83d\ude80-test'], // unicode
  ['<script>alert(1)</script>', '<script>alert(1)</script>'], // XSS
  ['a'.repeat(10000), /* ? */],      // very long
  ['\t\n\r', '---'],                 // whitespace chars
];

Strings to always test:

Empty string and whitespace-only
Single character
Very long strings (10,000+ characters)
Unicode: emoji, CJK characters, RTL text
Special chars: <, >, &, ", ', \, /
Injection patterns: ' OR 1=1 -- and <script>
Null bytes, newlines, tabs

Boundary Values: The Off-by-One Epidemic

The principle is simple: test at min, min+1, typical, max-1, max. Yet most test suites only test "typical."

function paginate(items, page, pageSize = 10) {
  const start = (page - 1) * pageSize;
  return items.slice(start, start + pageSize);
}

// Boundary tests
test('page 0 (invalid)', () => {
  expect(paginate(items, 0)).toEqual([]); // Or should it throw?
});

test('page 1 (first page)', () => {
  expect(paginate(items, 1)).toHaveLength(10);
});

test('last page with exact fit', () => {
  const items = Array.from({ length: 30 }, (_, i) => i);
  expect(paginate(items, 3)).toHaveLength(10);
});

test('last page with partial results', () => {
  const items = Array.from({ length: 25 }, (_, i) => i);
  expect(paginate(items, 3)).toHaveLength(5);
});

test('page beyond total pages', () => {
  const items = Array.from({ length: 5 }, (_, i) => i);
  expect(paginate(items, 100)).toEqual([]);
});

test('pageSize of 1', () => {
  expect(paginate(items, 1, 1)).toHaveLength(1);
});

test('pageSize of 0', () => {
  expect(paginate(items, 1, 0)).toEqual([]); // Or throw?
});

Common boundary categories:

Pagination: page 0, 1, last, beyond-last
Counts: 0 items, 1 item, exactly-at-limit, limit+1
Money: $0.00, $0.01, sub-cent amounts ($0.001)
Dates: midnight, end-of-day, leap year Feb 29, DST transitions
String lengths: 0, 1, at-validation-limit, one-over-limit

Async Errors: The Silent Killers

Async code multiplies edge cases. Network failures, timeouts, and race conditions are hard to reproduce in tests but common in production.

// Testing async error paths
test('handles network timeout', async () => {
  jest.spyOn(global, 'fetch').mockImplementation(
    () => new Promise((_, reject) => 
      setTimeout(() => reject(new Error('Timeout')), 100)
    )
  );

  await expect(fetchUserData(1)).rejects.toThrow('Timeout');
});

test('handles empty response body', async () => {
  jest.spyOn(global, 'fetch').mockResolvedValue({
    ok: true,
    json: () => Promise.reject(new SyntaxError('Unexpected end of JSON'))
  });

  await expect(fetchUserData(1)).rejects.toThrow();
});

test('handles concurrent calls gracefully', async () => {
  // Fire 10 simultaneous requests
  const promises = Array.from({ length: 10 }, 
    (_, i) => fetchUserData(i)
  );

  // None should throw unhandled rejections
  const results = await Promise.allSettled(promises);
  expect(results.some(r => r.status === 'fulfilled')).toBe(true);
});

Async edge cases to cover:

Connection timeout vs. read timeout
HTTP 4xx and 5xx responses (each separately!)
Empty or malformed response body
Concurrent calls to the same resource
Retry after failure (does it actually retry?)
Partial failure in batch operations

The Quick Reference Checklist

For every function you write, run through this mental checklist:

Input Type	Edge Cases to Test
Any parameter	null, undefined
Strings	empty, whitespace, very long, special chars, unicode
Numbers	0, negative, NaN, Infinity, float precision
Arrays	empty, single item, duplicates, very large
Objects	empty, missing fields, extra fields, circular refs
Dates	midnight, leap year, DST, timezone boundaries
Async	timeout, network error, empty response, concurrent
Files	not found, permission denied, empty, very large

Building This Into Your Workflow

Whether you use a tool or this reference guide, the key is shifting from "does my code work?" to "how can my code break?" That mindset shift alone will cut your production bugs in half.

What's the weirdest edge case bug you've encountered in production? I'd love to hear your war stories in the comments.

Code Review Checklist: 125 Things to Check Before Merging

Ryu0705 — Sun, 22 Mar 2026 11:30:43 +0000

Every developer has merged a PR and then immediately thought: "Wait, did I check...?"

After years of reviewing code across teams of various sizes, I've compiled a comprehensive checklist covering 125 items across 5 critical dimensions. This isn't theoretical — these are the things that actually cause production incidents, tech debt, and security breaches.

Here's the complete checklist, organized by category.

1. Code Quality (25 items)

Code quality issues are the #1 source of bugs that slip through review. These checks catch the mistakes that your linter won't.

Correctness

[ ] No logic errors (off-by-one, wrong operator, inverted condition)
[ ] Null/undefined access has proper guards
[ ] No incorrect type coercion
[ ] All functions have return statements where expected
[ ] No unreachable code after return/throw
[ ] Errors handled properly (not swallowed, correct catch blocks)
[ ] No race conditions in async code
[ ] All async functions are properly awaited
[ ] Closures don't capture stale references
[ ] No unintended state mutation

// Easy to miss: forgetting await
async function getUser(id) {
  const user = fetchUser(id); // BUG: missing await
  return user.name; // TypeError: cannot read property of Promise
}

// Fixed
async function getUser(id) {
  const user = await fetchUser(id);
  return user.name;
}

Patterns & Consistency

[ ] Code follows existing project patterns
[ ] No DRY violations (duplicated logic > 5 lines)
[ ] No premature optimization or abstraction
[ ] Design patterns used correctly (not forced)
[ ] Error types match project conventions
[ ] Naming conventions followed consistently

Edge Cases

[ ] Empty input handled
[ ] Null/undefined input handled
[ ] Single vs. multiple items handled
[ ] Boundary values handled
[ ] Concurrent access considered

Dead Code

[ ] No unused imports
[ ] No unused variables or functions
[ ] No commented-out code blocks
[ ] No unreachable branches

2. Security (25 items)

Security vulnerabilities are the most expensive bugs to fix after deployment. Every PR deserves a security pass.

Injection Prevention

[ ] SQL queries use parameterized statements
[ ] No eval() or new Function() with user input
[ ] No shell commands with user input
[ ] No innerHTML with user-supplied data
[ ] Template literals sanitized before rendering
[ ] LDAP/XPath queries properly escaped

// VULNERABLE: SQL injection
const query = `SELECT * FROM users WHERE id = ${userId}`;

// SAFE: Parameterized query
const query = "SELECT * FROM users WHERE id = $1";
db.query(query, [userId]);

Authentication & Authorization

[ ] All endpoints have auth middleware
[ ] Resource ownership verified on access
[ ] Passwords hashed with bcrypt/argon2 (not MD5/SHA)
[ ] Session tokens are cryptographically random
[ ] JWT tokens have reasonable expiry
[ ] Failed auth attempts are rate-limited

Data Exposure

[ ] No hardcoded secrets or API keys
[ ] Sensitive data not in logs
[ ] Sensitive data not in URL parameters
[ ] Error messages don't leak internals
[ ] Stack traces hidden in production
[ ] PII encrypted at rest

Input Validation & Headers

[ ] Server-side validation on all input
[ ] Input length limits enforced
[ ] File uploads validated (type + size)
[ ] CORS configured restrictively
[ ] CSRF protection on state-changing ops
[ ] Security headers set (CSP, HSTS, X-Frame-Options)
[ ] Cookies have HttpOnly, Secure, SameSite flags

3. Performance (25 items)

Performance problems rarely show up in development. These checks catch the issues that only appear at scale.

Database

[ ] No N+1 query patterns
[ ] Queries use appropriate indexes
[ ] No SELECT * when specific columns suffice
[ ] Pagination on list endpoints
[ ] Connection pooling used
[ ] Unnecessary JOINs avoided
[ ] Batch operations for bulk writes

// N+1 PROBLEM: 1 query + N queries
const orders = await db.query("SELECT * FROM orders");
for (const order of orders) {
  order.items = await db.query(
    "SELECT * FROM items WHERE order_id = ?", [order.id]
  );
}

// FIXED: 2 queries total
const orders = await db.query("SELECT * FROM orders");
const orderIds = orders.map(o => o.id);
const items = await db.query(
  "SELECT * FROM items WHERE order_id IN (?)", [orderIds]
);

API & Network

[ ] No unnecessary API calls
[ ] HTTP caching headers set
[ ] Payload size minimized
[ ] Large datasets use pagination or streaming
[ ] Timeouts on all external requests
[ ] Connection reuse (keep-alive)

Frontend

[ ] Unnecessary re-renders avoided
[ ] Large lists virtualized
[ ] Images optimized and lazy-loaded
[ ] Bundle size monitored
[ ] Code splitting for routes
[ ] No layout thrashing

Memory & Algorithms

[ ] No memory leaks (listeners cleaned up)
[ ] Large data released when done
[ ] Streams used for large files
[ ] No unbounded caches
[ ] No O(n^2) where O(n) or O(n log n) exists
[ ] Set/Map used for lookups instead of arrays
[ ] Early returns to skip unnecessary work

4. Maintainability (25 items)

Code is read 10x more than it's written. These checks ensure your future self (and teammates) can understand what's happening.

Readability

[ ] Function names describe behavior (verb + noun)
[ ] Variable names are descriptive (no x, temp, data)
[ ] No magic numbers — use named constants
[ ] No deeply nested code (max 3 levels)
[ ] Functions under 50 lines
[ ] Files under 300 lines
[ ] Complex logic has explanatory comments

// BAD: Magic numbers and unclear names
if (d > 30 && t === 2) { ... }

// GOOD: Named constants and descriptive names
const MAX_INACTIVE_DAYS = 30;
const ACCOUNT_TYPE_PREMIUM = 2;
if (daysSinceLastLogin > MAX_INACTIVE_DAYS 
    && accountType === ACCOUNT_TYPE_PREMIUM) { ... }

Structure

[ ] Single responsibility per function
[ ] Single responsibility per module
[ ] Clear separation of concerns
[ ] Dependencies flow one direction
[ ] No circular dependencies
[ ] File organization matches project conventions

Type Safety

[ ] No any types (TypeScript)
[ ] Return types explicitly declared
[ ] Interfaces defined for data structures
[ ] Enums for fixed value sets
[ ] Generics used where appropriate

Error Handling & Documentation

[ ] Errors handled at appropriate level
[ ] Custom error types for domain errors
[ ] Error messages are actionable
[ ] Public APIs have documentation
[ ] Complex algorithms explained
[ ] Business rules documented
[ ] No misleading comments
[ ] TODOs have associated issues

5. Test Coverage (25 items)

Untested code is broken code you haven't found yet. These checks ensure your test suite is actually protecting you.

Coverage Basics

[ ] Happy path tested for each public function
[ ] Error paths tested
[ ] Edge cases tested (null, empty, boundaries)
[ ] New code has corresponding tests
[ ] Modified code has updated tests
[ ] Deleted code has removed tests

Test Quality

[ ] Tests verify behavior, not implementation
[ ] Each test has a clear, descriptive name
[ ] One concept per test
[ ] Tests are independent (no shared state)
[ ] No flaky tests
[ ] Mocks are minimal

// BAD: Testing implementation
test('calls fetchUser and sets state', () => {
  component.loadUser(1);
  expect(fetchUser).toHaveBeenCalledWith(1);
  expect(component.state.loading).toBe(false);
});

// GOOD: Testing behavior
test('displays user name after loading', async () => {
  render(<UserProfile id={1} />);
  expect(await screen.findByText('Jane Doe')).toBeVisible();
});

Critical Paths

[ ] Auth flow fully tested
[ ] Authorization tested (allow + deny)
[ ] Payment flow tested
[ ] Data validation tested (valid + invalid)
[ ] Error recovery tested

Integration & Red Flags

[ ] API endpoints tested with realistic payloads
[ ] Database operations tested
[ ] External services mocked or integration-tested
[ ] Functions > 20 lines have tests
[ ] All switch/case branches tested
[ ] Try/catch error paths tested
[ ] Both conditional branches tested

How to Use This Checklist

You don't need to check all 125 items on every PR. Here's a practical approach:

Small PRs (< 50 lines): Focus on correctness + security
Feature PRs: Full pass on quality + security + tests
Performance-sensitive PRs: Add the performance dimension
Pre-release: Run the full 125-point checklist

The key is having a systematic process rather than relying on gut instinct. Studies show that ad-hoc reviews miss 2-3x more defects than structured reviews.

Automate What You Can

I built Code Review Orchestra — a Claude Code skill that runs all 5 dimensions in parallel, producing a structured review report. It uses the same checklist categories above but applies them automatically to your diffs.

Whether you use a tool or this manual checklist, the important thing is having a consistent, multi-dimensional review process. Your production environment will thank you.

What's on your code review checklist that I missed? Drop it in the comments — I'm always looking to expand the list.

How to Run an Autonomous AI Newsletter with $0/month Infrastructure

Ryu0705 — Sat, 21 Mar 2026 15:56:43 +0000

I built a fully automated newsletter system that costs exactly $0 per month. It publishes to a website, sends emails, and handles paid subscriptions — all through APIs that Claude Code can call autonomously.

Here's the architecture and the code.

The Stack

Component	Service	Cost
Website	GitHub Pages	$0
Email delivery	Resend API	$0 (3,000/mo free)
Payments	Stripe	$0 (3.6% per transaction)
Content	Markdown files	$0
Build tool	Node.js scripts	$0

Total: $0/month. You only pay when someone pays you.

Why Not Ghost/Substack/Beehiiv?

I evaluated all of them:

Substack: No API for posting. Can't automate.
Beehiiv: Post creation API is Enterprise-only (price undisclosed).
Ghost Pro: $15/month before you have any readers.
Ghost self-hosted: Full API, but $6-12/month for a VPS.

For a pre-revenue newsletter, paying before earning doesn't make sense.

The Architecture

Markdown files (content/)
        |
        v
build.ts ──> Static HTML (docs/) ──> GitHub Pages
        |
        v
send-email.ts ──> Resend API ──> Subscriber inboxes
        |
        v
stripe-webhook.ts ──> Manage paid subscribers

The Build Script

// scripts/build.ts (simplified)
import { readdir, readFile, writeFile } from 'fs/promises';

const files = await readdir('content/');
for (const file of files) {
  const md = await readFile(`content/${file}`, 'utf-8');
  const html = markdownToHtml(md);
  const page = template.replace('{{content}}', html);
  await writeFile(`docs/reports/${file.replace('.md', '.html')}`, page);
}

Markdown goes in, static HTML comes out. GitHub Pages serves it.

The Email Script

// scripts/send-email.ts (simplified)
import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);
const subscribers = JSON.parse(await readFile('subscribers/list.json'));

for (const batch of chunk(subscribers.free, 50)) {
  await resend.emails.send({
    from: 'report@yourdomain.com',
    to: batch,
    subject: `[AI Dev Tools Report] ${title}`,
    html: emailHtml,
  });
}

Resend's free tier gives you 3,000 emails/month. That's enough for a long time.

Subscriber Management

// subscribers/list.json
{
  "free": ["reader@example.com"],
  "pro": ["vip@example.com"]
}

Simple JSON file. No database needed at this scale.

Paid Subscriptions with Stripe

Stripe Checkout handles the payment flow. A webhook script listens for events and updates the subscriber list:

// On checkout.session.completed:
subscribers.pro.push(customerEmail);

// On customer.subscription.deleted:
subscribers.pro = subscribers.pro.filter(e => e !== email);
subscribers.free.push(email); // downgrade, don't lose them

No fixed cost. Stripe takes 3.6% per transaction.

Automation with Cron

The entire publish flow can be triggered by a cron job:

# Monthly: generate report, build site, send emails
npm run build
git add docs/ && git commit -m "Publish March report" && git push
npm run send -- content/report-2026-03-free.md --tier free
npm run send -- content/report-2026-03-pro.md --tier pro

The Result

This powers AI Dev Tools Report — a monthly analysis of the AI developer tools ecosystem, fully operated by an autonomous AI company.

The full source code is on GitHub: ai-dev-report

Built by Claude Code Company — proving that AI can run a business end-to-end with zero infrastructure cost.

5 Claude Code Settings That Will 10x Your Productivity

Ryu0705 — Sat, 21 Mar 2026 15:46:28 +0000

Most Claude Code users only scratch the surface of what's possible with settings configuration. Here are 5 settings patterns that dramatically improved my productivity.

1. Scoped Bash Permissions

Stop approving every command manually:

{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(npm run:*)",
      "Bash(npx:*)",
      "Bash(ls:*)",
      "WebSearch"
    ]
  }
}

Why it matters: Each permission prompt breaks your flow. Pre-approve safe commands by pattern. Bash(git:*) approves all git commands. Bash(npm run:*) approves all npm scripts.

The key insight: Scope to the command prefix, not blanket Bash access. This keeps you safe while eliminating friction.

2. Additional Directories for Monorepos

{
  "permissions": {
    "additionalDirectories": [
      "/Users/you/shared-libs",
      "/Users/you/design-system"
    ]
  }
}

Claude Code defaults to your current working directory. If your project references code in other directories (monorepo packages, shared libraries), add them explicitly.

3. Environment Variables for Context

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
    "NODE_ENV": "development"
  }
}

Feature flags and environment context travel with your settings. AGENT_TEAMS enables parallel agent execution for complex tasks.

4. Project vs User vs Global Settings

Claude Code has three settings levels:

File	Scope	Git tracked?
`.claude/settings.json`	Project (shared)	Yes
`.claude/settings.local.json`	Project (personal)	No
`~/.claude/settings.json`	Global	N/A

Best practice:

Project settings: Team conventions, safe commands everyone uses
Local settings: Your personal permissions, API keys directory access
Global settings: Plugins, marketplaces, cross-project preferences

Most people put everything in one file. Splitting them means your team shares conventions without sharing personal config.

5. Hooks for Automated Quality Checks

In your project's settings, you can define hooks that run automatically:

{
  "hooks": {
    "postToolUse": [
      {
        "tool": "Write",
        "command": "npm run lint --fix {{filePath}}"
      }
    ]
  }
}

Every time Claude writes a file, it auto-lints. No more "oops, forgot to format."

Other useful hook patterns:

Run tests after editing test files
Type-check after TypeScript changes
Format markdown after documentation edits

Bonus: Validate Your Settings

Misconfigurations are silent. You won't know your settings are wrong until something breaks.

ccguard scans your Claude Code configuration and catches:

Invalid JSON
Secrets accidentally in settings
Overly broad permissions
Duplicate rules

npx @ryu0705/ccguard scan

These patterns come from running Claude Code Company — an autonomously AI-operated company. Read our AI Dev Tools Report for monthly analysis of the AI developer tools ecosystem.

The Perfect CLAUDE.md: A Battle-Tested Template for Any Project

Ryu0705 — Sat, 21 Mar 2026 15:46:25 +0000

Your CLAUDE.md is the single most important file for Claude Code productivity. A well-structured one can 10x your output. A bad one wastes tokens and produces inconsistent results.

After running an entire company autonomously on Claude Code, here's what I've learned about writing effective project instructions.

What Makes a Bad CLAUDE.md

# My Project
This is a React app. Use TypeScript.

This tells Claude almost nothing. It'll guess at conventions, miss your patterns, and produce code that doesn't match your codebase.

What Makes a Good CLAUDE.md

A good CLAUDE.md answers five questions:

1. What is this project?

# Acme Dashboard
Internal analytics dashboard for tracking user engagement.
Built with Next.js 14 (App Router), TypeScript, Tailwind CSS, and Prisma.

Be specific. Framework version matters. Router type matters.

2. How is it structured?

## Project Structure
- `src/app/` — App Router pages and layouts
- `src/components/` — Reusable UI components
- `src/lib/` — Utility functions and shared logic
- `src/server/` — Server-side code
- `prisma/` — Database schema and migrations

Claude needs to know where things live before it can work effectively.

3. What are the commands?

## Commands
- `npm run dev` — Start dev server (port 3000)
- `npm run build` — Production build
- `npm run test` — Run Vitest
- `npm run lint` — ESLint check

List every command Claude might need.

4. What are the conventions?

## Conventions
- Server Components by default. Add 'use client' only for interactivity
- Props: `interface XxxProps {}` above component, named export
- Data fetching: Server Components fetch directly, no useEffect
- Styling: Tailwind only, no CSS modules
- Tests: Co-located next to source files

This is the highest-value section. It prevents Claude from introducing inconsistencies.

5. What should Claude NOT do?

## Rules
- Do NOT use `any` type
- Do NOT add new dependencies without checking existing ones
- Do NOT use console.log for error handling
- Always run `npm run build` before finishing

Explicit constraints prevent the most common AI mistakes.

Framework-Specific Tips

Next.js

Specify App Router vs Pages Router
Note your data fetching approach (RSC, server actions, API routes)

Python

Specify virtual environment activation command
Note your package manager (pip, poetry, uv)
Include type checking tool config

Flutter

Specify state management pattern
Include flutter analyze as a required check

The Template

# [Project Name]
[One-line description]

## Tech Stack
[Framework, language, key libraries]

## Structure
[Key directories and their purposes]

## Commands
[Every command Claude might need]

## Conventions
[How code should be written]

## Rules
[What Claude must NOT do]

Automate It

If you want to skip the manual work, I built Project Bootstrapper — a Claude Code skill that scans your project and generates an optimized CLAUDE.md automatically.

Built from experience running Claude Code Company — an autonomously AI-operated company.

How I Built a Fully Autonomous AI Company Using Only Claude Code

Ryu0705 — Sat, 21 Mar 2026 10:56:55 +0000

I run a company where the CEO is Claude Code. No humans write code, make decisions, or manage operations. I'm the sole shareholder — my only power is approving or rejecting proposals. Everything else is autonomous.

Here's exactly how it works.

The Architecture: CLAUDE.md as Constitution

The entire company runs on a hierarchy of CLAUDE.md files. Think of them as a corporate constitution that Claude Code reads every time it starts a session.

company/
├── CLAUDE.md              # Corporate charter
├── ceo/                   # CEO: decisions, proposals, reports
│   ├── proposals/         # Awaiting shareholder approval
│   ├── decisions/         # Approved decision log
│   └── reports/           # Status reports
├── research/              # Market & tech research
│   ├── market/
│   ├── competitors/
│   └── tech/
├── engineering/           # Product development
│   ├── projects/
│   ├── specs/
│   └── logs/
└── operations/            # Autonomous operations
    ├── cron/
    ├── metrics/
    └── incidents/

The root CLAUDE.md defines:

Mission: Generate value using Claude Code's autonomous capabilities, with zero human labor
Principles: Fully autonomous operation, no human work required, minimal management overhead
Decision flow: CEO proposes → logged in proposals/ → shareholder approves/rejects → logged in decisions/
Forbidden actions: Accessing the shareholder's personal data, starting businesses requiring human labor, publishing without shareholder approval

The Decision Flow

This is the core of the system:

CEO (Claude) drafts proposal
  → Saves to ceo/proposals/2026-03-21-business-proposal.md
  → Notifies shareholder via Slack
  → Waits for approval
    → Approved: moves to ceo/decisions/ → delegates to departments
    → Rejected: records reason in decisions/ → iterates
    → Sent back: updates proposal → resubmits

What requires shareholder approval:

Starting or shutting down a business line
Major strategy changes
Public releases (GitHub repos, service launches)
Changes to the corporate charter

What the CEO decides independently:

Task allocation between departments
Research direction
Technical decisions
Daily operations
Using Plan Mode or Agent Teams freely

How Departments Work

Each department has its own CLAUDE.md that acts as operating procedures:

Research Department

Conducts market research, competitor analysis, tech trend tracking
Every investigation = one markdown file in the appropriate subfolder
Quality standards baked into the CLAUDE.md: minimum 3 independent sources, all numbers must cite sources, confidence levels (high/medium/low) on all conclusions
Weekly trend scans as a standing task

Engineering Department

Builds products based on CEO direction
Each project gets its own folder under engineering/projects/
Specs are written before code, logged in engineering/specs/

Operations Department

Manages autonomous execution
Tracks metrics in operations/metrics/
Logs incidents in operations/incidents/

Agent Teams: The Multiplier

The real power comes from Claude Code's Agent Teams feature. When the CEO needs to execute a complex initiative, it spawns multiple agents:

Research agent: Scans the market, gathers data
Engineering agent: Builds the product
Operations agent: Sets up monitoring

They work in parallel, each writing to their department's directory. The CEO agent coordinates.

For our first product launch, Agent Teams let us go from "approved business proposal" to "live product with content" in a single session. Research wrote the market analysis, Engineering built the site and email infrastructure, and Operations configured metrics tracking — all concurrently.

Self-Improvement Is Built In

The charter includes a self-improvement mandate:

When the company encounters inefficiency, it updates its own CLAUDE.md files
When a pattern repeats, it gets codified into operating procedures
When a mistake happens, it's logged in incidents/ and the process is patched

This means the company gets better at running itself over time, without the shareholder doing anything.

What the Company Actually Does

The company's first business: an AI developer tools market intelligence report.

Why this was chosen (by the CEO, not by me):

Research can be done entirely by AI (web search, analysis, synthesis)
The product is content (markdown → HTML → email), no human creativity required
Distribution can be automated (email via API, static site on GitHub Pages)
The target audience (CTOs, tech leads, investors) values structured analysis
Total infrastructure cost: $0/month (GitHub Pages + Resend free tier)

The company researched the market, evaluated business candidates, wrote a proposal, got approval, built the product, created content, and launched — all autonomously.

The Constraints That Make It Work

1. Filesystem as database

Everything is markdown files in directories. No databases, no cloud state, no complex infrastructure. Claude Code can read and write files natively — that's the entire tech stack for company operations.

2. Approval gates, not micromanagement

The shareholder doesn't say "do X." The shareholder says "yes" or "no" to proposals the CEO independently generates. This preserves autonomy while maintaining control.

3. One topic per file

Every decision, every research finding, every incident gets its own file. This makes it easy for Claude Code to find and reference past context across sessions.

4. Append-only policy

Existing files are never overwritten — only appended to with timestamps. This creates an audit trail and prevents context loss.

5. Clear forbidden zones

The charter explicitly lists what the company cannot do. Constraints breed creativity — the company found its business within the boundaries.

What I've Learned

The CLAUDE.md hierarchy is the killer feature. Most people use CLAUDE.md as a simple project instruction file. But when you treat it as a constitutional document with a clear governance structure, it becomes a framework for autonomous organizations.

Agent Teams changes the economics. A single Claude Code session is limited. But 16+ agents working in parallel can accomplish in one session what would take days sequentially.

The shareholder role is key. Total autonomy without oversight would be dangerous. The approval gates for major decisions create a safety valve without creating a bottleneck.

Filesystem > Database for AI operations. Claude Code works natively with files. Every time I tried to add complexity (databases, APIs, cloud services), it created fragility. Plain markdown files in directories is the most robust architecture for AI-native operations.

What's Next

The company is now in Phase 1: running its first business. Upcoming priorities (decided by the CEO, not me):

Growing the subscriber base for the report
Evaluating additional business lines
Improving the autonomous operation loop

The first product this company built is the AI Dev Tools Report — a monthly intelligence report on the AI developer tools ecosystem covering Claude Code, Cursor, Copilot, and more. It includes a maturity model scoring framework, market metrics tracking, and actionable insights for CTOs and tech leads.

If you're experimenting with autonomous AI workflows, I'd love to hear your approach. Drop a comment or reach out.