Luke Stahl's Blog

Prompting is quick. Shipping a website isn't.

Fri, 12 Jun 2026 00:00:00 GMT

Vibe coding a site is fast. Both of my production sites were built with Claude. What took the rest of the time was everything underneath it: the DNS, email deliverability, analytics, SEO that works for humans and AI assistants, Core Web Vitals, payments, design, automation. None of it shows up in the prompt that built the homepage.

This isn't a critique. I'm all for it AI assisted building. The question is what comes next and what you do after the site looks good.

The two sites

Shacksbloom.com runs a florist business. Nine public pages (Home, Services, Portfolio, About, Inquire, Pay, Privacy, Terms, and a standalone Instagram page) plus an admin portal behind auth. The visible part is the easy part.

Lukestahl.io is this site. Astro 6 with Notion as the CMS, deployed to GitHub Pages. Blog, project listings, an AI models guide that checks for model updates every Monday and opens a PR when it finds them, a monthly newsletter built from scratch. Started with plain HTML, CSS, and JS, then migrated to Astro and React once the site needed more structure. Both of these sites are in production.

Tech stack decisions

Most of the time, these decisions happen before the first prompt, although sometimes a good conversation between you and your agent can help in the decision making.

For shacksbloom.com: Vite + Vercel. React (Single Page Application) SPA with build-time prerendering. Each deploy runs a prerender script that generates static HTML per route. No running SSR server, just HTML snapshots Vercel serves directly. Two people touch it and neither needs a CMS yet. I did however connect this site to Builder.io’s Fusion product for visual editing. This is best for the non-technical team member who needs to make edits and submit via PR to GitHub.

For lukestahl.io: started with plain HTML, CSS, and JS, then migrated to Astro once the site needed real structure. Astro handles static page building; React handles interactive components like Shadcn UI. Posts live in Notion, sync at build time, render to static HTML. Adding a post is a Notion edit and a deploy. The stack should fit how you work, not the other way around. I prefer Notion because it’s where I like to write content via their editor rather than within a CMS. I don’t have team members that I require a CMS.

Stack mismatches show up later in the build. A framework that defaults to SSR when you're serving mostly static content adds complexity everywhere. Don't let a prompt make that call.

Design: I'm not a designer

Both sites needed design work. Before Claude Design existed, I was having Claude generate self-contained HTML files with inline styles, opening them in a browser, screenshotting what worked, and feeding that context back into the next session. I also used the Excalidraw MCP to export those HTML files into hand-drawn style visuals. More character than a polished AI mockup, and a useful middle ground between wireframe and finished design.

Claude Design changed the workflow considerably. Where I was stitching together HTML mocks, browser screenshots, and context drops, now I iterate in a design-system-aware tool. The output lands closer to finished when you bring intent to it. The "AI slop" label is becoming something people throw around to sound above it, or maybe because they're nervous about what it means for designers. I understand both positions. Not being a designer with access to these tools means I can ship sites that look like a designer worked on them. Nobody one-shots a design and ships it. The output on pass one is a starting point. Push back on defaults, redirect what's off, keep going. The output gets better every pass. That's the whole job, same as it's always been.

Excalidraw is worth knowing regardless of the AI workflow. It handles everything from rough architecture sketches to clean professional diagrams, and the hand-drawn aesthetic is a deliberate choice you can switch on or off. For visual thinking, system diagrams, and design assets that need a bit of character, it's one of the better tools out there. The MCP integration is a bonus: take an HTML mock, run it through, and you get a hand-drawn version that doesn't look like it came straight out of an AI tool.

DNS and deployment

The DNS chain for shacksbloom.com runs GoDaddy → Cloudflare → Vercel. Vercel terminates SSL, which means every Cloudflare record has to stay on DNS-only mode. Flip one record to orange-cloud and HTTPS breaks. That detail isn't documented anywhere visible. You find it by breaking things.

Cloudflare Email Routing came free with the domain. jackie@shacksbloom.com and hello@shacksbloom.com forward to Gmail without a Google Workspace account. hello@ is a catch-all. Small thing that eliminates a recurring cost.

Lukestahl.io is simpler at the DNS layer. GitHub Pages handles SSL and deployment. The complexity lives in the build pipeline.

Email infrastructure

Both sites use Resend for transactional email. Resend's free tier allows one verified domain per account, so shacksbloom.com and lukestahl.io each have their own. DKIM on each domain. SPF on the send subdomain. A p=none DMARC record at minimum: skip it and sending works fine for weeks, then Gmail starts routing inquiry replies to spam. No error, no warning. It just stops working.

The shacksbloom.com inquiry handler is a Vercel function at api/inquire.ts. It validates required fields, silently drops honeypot-flagged submissions, sends Jackie a styled HTML email with Reply-To set to the person inquiring, and fires an auto-reply. The API key is scoped to sending on shacksbloom.com only.

Lukestahl.io has a monthly newsletter. Not Mailchimp, not Beehiiv. Custom-built. Resend handles delivery. The list, scheduling, and template rendering are all code I own: no subscriber caps, no platform fees, templates that match the site exactly. It's one more thing to maintain, and it runs exactly how I want it to.

Analytics and automation

Both sites run PostHog. For shacksbloom.com, it's proxied through /ingest/* so ad blockers don't drop the events. Five explicit events, autocapture off, session replay scoped to the inquiry flow so I'm not burning the free tier watching generic page views.

For lukestahl.io, same setup without the proxy. Analytics feed content decisions: which posts get read, where people land, what converts to newsletter signups.

Automated GitHub Actions handle monitoring on lukestahl.io:

A link checker that emails me via Resend when internal or external links break
A Core Web Vitals monitor that opens a GitHub issue when LCP, CLS, or INP regress on tracked pages
An AI models guide updater that pulls Anthropic and OpenAI release feeds, runs a diff through a prompt, pushes a branch, and opens a PR when it finds changes

For shacksbloom.com, a GitHub Actions workflow runs every Monday, queries PostHog for the prior week, and emails a summary to Jackie and me via Resend.

Slack integrations are connected via PostHog workflows for lukestahl.io and scheduled sends on Monday via a Content Agent. This helps monitor changes week over week if I want a quick report vs going into PostHog’s dashboard. PostHog’s MCP also helps create custom dashboards that I highly recommend.

SEO and AEO

Core Web Vitals affect ranking directly. Let LCP, CLS, or INP regress on mobile and organic traffic follows. The GitHub Actions monitor surfaces regressions before they add up to a traffic drop. These GitHub Actions also run weekly with a GitHub action for deployment to lukestahl.io/seo/.

AEO is the other half: making the site readable and useful to AI assistants. Both sites have llms.txt files that explain what each site is for. Lukestahl.io has JSON-LD structured data on every post, an IndexNow integration that notifies Bing and Yandex within minutes of a new page, and a sitemap with canonical URLs and noindex filtering. Shacksbloom.com's llms.txt includes the payment page URL so an AI assistant can hand it to someone asking "how do I pay Jackie?"

LLMs.txt:

Both sites run weekly Ahrefs audits. It surfaces broken links, crawl errors, missing metadata, and issues that don't show up in any build output. It's the tool that keeps SEO health visible on an ongoing basis rather than something you check once at launch and forget.

One thing it caught on shacksbloom.com: the homepage was flagged as orphaned three weeks after launch. Same index.html served every route, empty <div id="root">, no internal <a> tags visible to crawlers without JavaScript. The fix was a prerender step that emits a fully-hydrated HTML body per route. Most LLM scrapers and older search crawlers don't execute JavaScript. If your build emits a shell, those crawlers see a blank page.

Payments

Shacksbloom.com has a /pay page. A Venmo deep-link button that opens the app on mobile and falls back to the web on desktop. A Zelle card with copy-to-clipboard for the receiving email. No Stripe, no transaction fees on small deposits.

It's indexed, linked from the footer, and listed in llms.txt. Simple setup, but the discoverability piece matters. If someone asks an AI assistant how to pay for a custom arrangement, the assistant can surface the link.

Instagram

Shacksbloom.com/instgram pulls a live Instagram feed via Behold.so. The floral work is the product, and Instagram is where the portfolio lives. Behold.so handles the API connection and caching on their end; the site loads a widget script and stays current without a build.

Admin portal

Shacksbloom.com has a custom admin portal built on Neon serverless Postgres with Drizzle ORM, auth via Clerk backed by Google OAuth, and a full quote-to-invoice lifecycle. The entire admin bundle is lazy-loaded so none of its JS ships to public visitors.

Getting Clerk to production with Google OAuth isn't just enabling a toggle. You need a Google Cloud project, OAuth credentials with a client ID and secret, and authorized redirect URIs pointing to Clerk's callback, all wired into Clerk's dashboard. Most tutorials skip that step entirely. Once Google auth clears, there's a second layer: the user's email is checked against an ADMIN_EMAILS env var. The frontend blocks rendering if it fails, and every API call independently re-verifies the Clerk session token and re-checks the allowlist server-side. Two separate enforcement points, not one.

A quote starts as a draft, gets sent to the customer, and converts to an invoice when the job is confirmed. Invoices track payment method and paid date. Refunds are their own invoice type linked back to the original. Every quote and invoice has line items with description, date, notes, and amount. Every invoice can be emailed to the customer as a branded PDF, rendered server-side via @react-pdf/renderer with Jackie's logo, and every send is logged to an email_logs table with the Resend message ID and delivery status. A year view shows total collected, receipt count, and refund count.

This only works because one developer manages both sites. Build vs. buy math changes fast once you add team members or operational complexity. For a personal site or a small business where one developer owns the whole stack, custom-built is often the right call.

Knowledge is key

The jump from a fun vibe-coded site to one that's built to last isn't about the framework or the code quality. It's about knowing what needs to exist. Having an agent to gut-check ideas, bake a plan, and work through the checklist with you gets you there considerably faster. My main advice is to treat your agent as a team member and dive into the laundry list of deliverables needed to go from this looks pretty to this can scale.

PLG for developer companies

Tue, 05 May 2026 00:00:00 GMT

The core idea

PLG is not a marketing motion. It's the discipline of letting your product, your pricing, and your free tier do the work that a sales team does at a sales-led company. Sales is the layer you add on top once adoption is happening. Never the layer you start with.

Most companies miss this because they treat PLG as a tactic to bolt onto an existing motion. They run a 14-day trial, gate the API behind a sales call, charge per seat, and wonder why developers churn before they activate. The order matters. So does each individual decision inside it.

The companies that scaled developer products past $100M ARR (Stripe, Twilio, Vercel, Algolia, Datadog, MongoDB, GitHub, Cloudflare) didn't do this by accident. They got the same set of decisions right, in roughly the same sequence. This is that sequence, in 10 steps.

1. Ship a free tier with utility — your acquisition channel

Not a 14-day trial. Not a "contact sales" form. A free tier where a developer can build something, deploy it, and run it in production before paying. The free tier is your acquisition channel.

Stripe charges nothing until a developer processes a transaction. Vercel's free tier includes deployments, serverless functions, and a production URL. Twilio gives free credits, and developers send SMS messages during integration. Algolia provides 10K search requests a month for free. What these have in common: a developer can build something they'd be embarrassed to lose.

That's the activation bar. Not signups, not free-account counts. If your free tier is a demo environment with watermarks and sandbox-only limits, it's a trial, and trials don't drive PLG. Trials drive sales calls.

The most common mistake is time-based gating. A 14-day trial creates an artificial deadline that pushes developers into a buying decision before they've integrated. Usage limits don't. A developer can integrate Stripe and run in test mode for years before paying anything. By the time they do pay, they've shipped a checkout flow, embedded the API in their stack, and accumulated months of historical data they don't want to migrate. That's lock-in earned through utility, not contracts.

Everything above assumes near-zero marginal cost per free user. That assumption breaks when your product includes AI-powered features. Every prompt, generation, or inference call burns compute. The free tier still needs to exist, but it can't be open-ended. Usage caps on AI features replace unlimited access. Gate volume and speed, not feature access. Midjourney does this with Fast Mode vs. Relax Mode. Fast Mode gives instant GPU access with limited monthly hours. Relax Mode is unlimited but queued. Users pay for priority and throughput, not better outputs.

The trap is building a free tier so capable that it removes the reason to upgrade. Google's AI team ran into this launching Gemini subscriptions. The free tier already outperformed most use cases. Users had no reason to pay. The fix wasn't restricting features. It was designing a ceiling that creates upgrade desire without killing the experience that gets developers hooked in the first place.

Checklist

Audit your free tier. Can a developer build and ship something production-grade without paying?
Remove time-based trial gates. Usage limits work. Countdown timers don't.
Track what percentage of free-tier users build something they'd be embarrassed to lose. That's your activation rate.
If your product includes AI features, define where free stops and whether that stopping point creates the right motivation to upgrade.

2. Time to first meaningful action — the metric that predicts everything

Time to first API call is the strongest predictor of developer conversion. Every friction point between signup and value drags conversion down. It doesn't matter how good your product is downstream if developers don't get there.

The number to measure is the median time from signup to a developer's first meaningful action. For Stripe, that meant a working checkout flow in under 15 minutes. For Twilio, it was the "send your first SMS" tutorial, not docs, not a dashboard tour. For Firebase, quickstart templates that deploy a working backend in under five minutes.

The mistake here is measuring the wrong moment. "Account created" is not first action. "Logged in" is not first action. First action is the moment a developer sees the product do something useful for their use case. That's specific to your product, and you have to define it precisely. For a payments API, it's a successful test charge. For a database, it's a query returning data. For a deployment platform, it's a live URL.

Track median time-to-action weekly. Identify the top three friction points between signup and that action (onboarding flow, key generation, SDK install, first request) and fix the biggest one each quarter. Time-to-action improvements ripple through every metric downstream.

Checklist

Define your first meaningful action precisely. Not signup, not login. The moment a developer creates something useful for their use case.
Measure the median time from signup to that action and track it weekly.
Identify the top three friction points between signup and first action. Fix the biggest one this quarter.

3. Activation is not signup — define it in one sentence

A signup is not a user. OpenView's PLG benchmarks show PLG companies are 2x more likely than sales-led companies to grow revenue 100% year over year, and 87% of standout PLG companies track an explicit activation metric.

Activation is the moment a developer experiences the product's core value for their use case. It has to be specific enough that an analyst can query it from your data warehouse on a Monday morning and a number comes back.

Slack defined activation as "2,000 messages sent by a team." That single metric reshaped their entire GTM strategy: every onboarding decision, every paid feature, every sales handoff was built around getting teams to 2,000 messages. Datadog defined activation as connecting a first integration and sending data. Amplitude defined it as a user creating their first saved chart.

If you can't write your activation metric in one sentence, it's too vague. If you can't query it from your warehouse today, it doesn't exist yet. And if you're still reporting signup counts to leadership without activation rates alongside them, you're making decisions on the wrong number.

Checklist

Write a one-sentence activation definition. If it takes more than one sentence, it's too vague.
Instrument it. If you can't query it from your data warehouse today, it doesn't exist yet.
Stop reporting signup counts to leadership without activation rates alongside them.

4. Visible artifacts — your organic loop runs on these

The strongest PLG loop: developers build things with your product that other developers can see. Those artifacts drive organic discovery without marketing spend.

Vercel's free-tier sites deploy to a vercel.app subdomain by default. Every deployment surfaces the brand. Netlify's deploy previews in GitHub PRs exposed the product to every reviewer on the team. Stripe's checkout pages are seen by millions of end users. Every transaction surfaces the brand. Webflow's published sites include Webflow branding on free plans, and every site is a billboard for the platform.

The pattern: the product creates artifacts visible to non-users. Sites, apps, APIs, integrations, embeds, deploy logs, share links. Make attribution easy but not mandatory. Make the artifact good enough that developers want to share it. And track the inbound signup volume that originates from product-generated artifacts. That's your organic loop metric, and it's the closest thing to a free customer acquisition channel that exists in B2B.

If your product doesn't create visible artifacts, you have a harder PLG problem. Internal tooling, backend-only services, and infrastructure-layer products have to find their visible surface elsewhere: open source, public docs, technical content, conference talks. The loop still has to exist. The channels are different.

Checklist

Identify what artifacts your product creates that are visible to non-users — sites, apps, APIs, integrations, embeds, deploy logs, share links.
Make attribution easy but not mandatory.
Track inbound signups that originate from product artifacts. That's your organic loop metric.

5. Self-serve onboarding — if a developer needs sales, it's not PLG

If a developer needs to talk to a human to get started, you don't have a PLG motion. You have a sales-led motion with a free tier on top. Docs, quickstarts, templates, and example projects do the work.

Stripe's documentation is the gold standard. Every API endpoint includes a working code example. Supabase built project templates that deploy a working app in one click. Neon's CLI creates a working Postgres database with one command, no dashboard required. None of these required a sales call to evaluate.

Run the new-developer test. Take someone who has never used your product, sit them in front of a clean machine, and time how long it takes them to sign up, build something, and deploy it without talking to anyone. If they can't, fix what blocks them before fixing anything else.

Two specific calls. First, prioritize quickstarts over comprehensive documentation. Developers want to start, not read. Comprehensive docs come second. Second, build at least one template or starter project that runs end-to-end in under 10 minutes. The developer who ships something in 10 minutes activates. The developer who spent an afternoon reading already churned.

Checklist

Run the new-developer test. Sit someone down at a clean machine and time how long it takes them to sign up, build, and deploy without talking to anyone.
Prioritize quickstarts over comprehensive docs. Developers want to start, not read.
Build at least one template or starter project that runs end-to-end in under 10 minutes.

6. Usage-based pricing — per-seat is friction at the wrong moment

Usage-based pricing aligns cost with value. Per-seat pricing creates friction at the exact moment you want expansion, when a second or third developer wants to start using the product.

Twilio charges per API call. Vercel charges based on bandwidth and serverless function execution. Cloudflare Workers charges per request after a generous free tier. Algolia charges per search request. In all of these, cost scales with the product's success, not headcount. A team of five developers using Stripe doesn't cost more than a team of one developer doing the same volume. That's the right answer.

Map your pricing to the unit of value a developer gets. API calls, deployments, executions, storage, bandwidth, requests, GB processed. Pick the metric that's easiest to explain on a single line and that a developer can predict from their usage. Predictability matters as much as fairness.

Two tests for your pricing model. First, is $0 a starting point? Usage limits beat time limits. A developer should be able to run on the free tier indefinitely, with the bill kicking in only when usage crosses a threshold. Second, what happens when a customer 10x's their usage? If the answer is "they call sales," you have a pricing wall, not a growth model. The whole point of usage pricing is that growth happens automatically.

Pure per-unit billing has a failure mode at scale: bill shock. Vikas Kansal's team at Google hit this building AI subscription tiers. Unpredictable costs make enterprise buyers nervous and individual developers hesitant. The alternative is intensity tiers. Prepaid volume buckets (Plus/Pro/Ultra) that give predictability while still aligning cost with usage. Developers get a taste of most capabilities in every tier, but volume and speed increase as they move up. Predictable tiers convert better than open meters because developers can budget for them.

There's a second dimension most developer tools haven't considered yet: outcome-based pricing. Instead of charging per input (API call, prompt, request), charge per successful result. Intercom's Fin AI agent charges $0.99 per resolution. The AI tries to answer for free. You only pay when the problem is solved. As developer tools add agent and automation capabilities, pricing per outcome starts to make more sense than pricing per request. A developer who pays per successful deployment or per resolved issue is paying for value delivered, not compute consumed.

Checklist

Map your pricing to the unit of value a developer gets — API calls, deployments, executions, storage, bandwidth, requests.
Make $0 a starting point. Usage limits beat time limits.
Model what happens when a customer 10x's their usage. If the answer is "they call sales," you have a pricing wall, not a growth model.
If your product has AI-powered features, map each feature to its compute cost. Pricing tiers should align with cost-to-serve, not just perceived value.
Evaluate whether any capability in your product could be priced on outcomes (successful completions, resolved issues, deployed builds) instead of inputs.

7. Product-qualified leads — instrument behavior, not vibes

A product-qualified lead is a user whose behavior signals they're ready for a paid plan or a sales conversation. The threshold should be specific and defensible, not a gut feeling.

Dropbox's PQL signal was a user hitting their storage limit. Atlassian identified PQLs based on growing team size on free Jira instances. Figma's PQL signal was 3+ editors working in shared files, the moment usage shifted from solo to collaborative. In each case, the signal was behavioral, queryable, and tied to expansion intent, not "this account looks active."

Define two or three behavioral signals that predict conversion from free to paid. Test them against historical data before you trust them. The simplest scoring model (signal A plus signal B equals PQL) outperforms guessing every time, and it gives sales something concrete to act on.

When PQLs do route to sales, route them with context. Not "this account is active." Specifically: three developers running production workloads across two workspaces, last 30-day request volume up 4x, hitting rate limits on the free tier. Sales will only land calls where the signal is strong, and the signal is only strong when it's specific.

For products with variable cost-to-serve, PQL scoring needs a cost dimension. A developer running 500 prompts a day is both your best conversion candidate and your biggest margin risk. Score for conversion likelihood and cost-to-serve simultaneously. High engagement plus high compute cost means this user needs to convert now, not eventually. The free tier is subsidizing their usage, and the longer they stay free, the worse your unit economics get.

Checklist

Define two or three behavioral signals that predict conversion from free to paid. Test them against historical data before you trust them.
Build a simple PQL scoring model. Signal A plus signal B equals PQL beats guessing.
Route PQLs to sales with specific context — developer count, workload type, usage trend, rate-limit hits — not "this account looks active."
Track cost-per-user alongside engagement-per-user. High engagement plus high cost equals your most urgent conversion target.

8. Bottom-up adoption — let developers pull the product into their org

Bottom-up adoption is the bet that individual developers will use the product first, then bring it to their team and their org. Enterprise features matter, but they come after individual adoption, not before.

GitHub grew inside enterprises one developer at a time, before it sold top-down to IT. Slack spread team by team: one team adopted, adjacent teams noticed, and IT eventually had to standardize. Datadog entered orgs through a single DevOps engineer monitoring one service. Each of these scaled because individual developers could get full value from the product without needing org-level approval.

The most important rule: no admin-only features in the critical path. If a developer can't use your product without their CTO clicking a button, you've broken bottom-up adoption. Permissions, billing, and SSO matter, but they should be optional add-ons, not blockers to first use.

Build sharing and collaboration features that naturally expose the product to non-users. When one developer adopts the product, the next developer should encounter it within a week: a shared link, a PR, a deploy preview, a notification, an artifact in the repo. Track the internal referral pattern. When a second developer joins an account, what triggered it? That trigger is your expansion lever.

Checklist

Make sure a single developer can get full value without org-level approval. No admin-only features in the critical path.
Build sharing and collaboration features that naturally expose the product to non-users.
Track internal referral patterns. When a second developer joins an account, what triggered it?

9. Expansion triggers — one developer is adoption, three is expansion

The moment one developer invites a second, or one workspace connects to a second, that's your expansion signal. This is the bridge between individual adoption and team or enterprise revenue, and it's the metric that separates products that grow from products that plateau.

Notion's expansion came from page-sharing. A user shares a page with a teammate, the teammate joins the workspace, and the account grows. Cross-account sharing was a stronger upgrade signal than any solo-usage metric. Linear's signature expansion event is the second engineer joining a workspace. Figma's was a design file shared with a developer, because cross-functional sharing predicted enterprise deals.

The pattern across all of these: the expansion signal is "more people or more projects," not "more usage." A single developer using the product more isn't expansion. A second developer joining is.

Measure active developer density per account. One developer is adoption. Three is expansion. That's the threshold where sales should engage. Earlier and you're spending sales time on accounts that aren't ready. Later and you're missing the window. Build features that make multi-developer collaboration better than solo use, because the moment collaboration is the obvious choice, expansion happens by default.

Checklist

Define your expansion signal as "more people or more projects," not "more usage."
Measure active developer density per account. One is adoption, three is expansion. That's the threshold for sales engagement.
Build features that make multi-developer collaboration better than solo use.

10. Product-led sales — sales is a layer, not a starting point

Elena Verna calls this product-led sales. Developers adopt bottom-up. Buyer personas (directors of engineering, tech leads, CTOs) approve expansion and budget. Sales engages accounts where adoption is already happening, not accounts where it might.

Twilio's sales team only engaged accounts after developers were already making API calls. Sales opened with usage data, not feature demos. MongoDB's enterprise sales targeted companies where Atlas free-tier clusters were already running. Vercel's enterprise motion focused on companies where multiple developers had already deployed projects. In all three, sales worked because the product had already done the trust-building.

Define the product adoption threshold that triggers a sales touchpoint. "Three or more active developers in one account" is better than "high engagement." The threshold has to be queryable and defensible. Sales should know exactly why this account got escalated.

The other half of this rule: don't let sales engage accounts below the adoption threshold. Premature outreach damages developer trust faster than anything else you can do. A developer who got a cold sales email two days after signing up will remember it, and they'll associate the friction with your product. Hold the line on the threshold even when pipeline pressure builds, because the alternative is faster pipeline this quarter and worse retention forever.

Checklist

Define the product adoption threshold that triggers a sales touchpoint. "Three or more active developers in one account" beats "high engagement."
Equip sales with product usage data — which products are in use, how many developers are active, what the growth trend looks like.
Don't let sales engage accounts below the adoption threshold. Premature outreach damages developer trust.

The order matters

These 10 steps aren't independent. They're a sequence, and each one only works because the previous ones are in place.

A free tier with utility doesn't drive growth without short time-to-action. Time-to-action doesn't matter if your activation metric is undefined. Activation can't be measured if you're charging per seat. Per-seat pricing kills the bottom-up adoption that PQLs depend on. PQLs are noise without an expansion signal. And expansion signals don't matter if sales engages accounts before they fire.

Companies fail at PLG because they pull one piece out of the sequence and bolt it onto a different motion. Free tier without usage pricing. Usage pricing without an activation metric. Activation metric without bottom-up adoption. The 10 steps above are the same set of decisions Stripe, Vercel, Twilio, Algolia, and Datadog all made, in roughly the same order.

If you're starting a developer product today, the order to follow is the order in this list. If you're adopting PLG inside a company that already has a sales motion, the order matters even more, because the friction will be highest at the steps where your existing motion contradicts the playbook. Find the contradiction and fix the contradiction. Don't try to run both at once.

PLG is the growth half of building a durable developer company. The other half is how companies innovate in the AI era.

Building developer tools for agents (not just humans)

Tue, 28 Apr 2026 00:00:00 GMT

The core problem

Most developer tools were built for humans. A developer reads your docs, copies your quickstart, integrates your SDK, and ships. That loop worked for 20 years.

The loop is changing. AI agents do more of that work now: reading docs, writing integration code, making API calls. Claude Code, Cursor, and Copilot don't browse your docs the way a human does. They need your product to be machine-readable, composable, and permission-aware in ways that most tools weren't designed for.

This doesn't mean rebuilding from scratch. It means understanding what changes when the primary consumer of your developer product is an AI agent rather than a human, then adapting deliberately.

The companies that do this well will deepen their moat. The companies that don't will find themselves irrelevant as agent-native alternatives emerge.

1. API design — the foundation

If your API isn't clean, nothing else matters. Agents pattern-match. Inconsistency breaks that pattern-matching immediately. A human developer can work around a poorly designed API by reading between the lines. An agent can't.

Consistency above everything

Every design decision that seemed minor when humans were the primary users becomes critical when agents are calling your API thousands of times autonomously.

Resource naming:

// Inconsistent — breaks agent pattern matching
GET /getUserById
POST /create_project
DELETE /org-member-remove

// Consistent — agents can predict URL structure
GET /users/{id}
POST /projects
DELETE /organizations/{org_id}/members/{user_id}

Rules that matter:

Nouns for resources, verbs for actions
Consistent casing throughout. Pick snake_case or camelCase, never mix
Predictable URL hierarchy: /resource/{id}/sub-resource/{sub_id}
HTTP methods used semantically. GET retrieves, POST creates, PUT replaces, PATCH updates, DELETE removes

Predictable response structures

Every response, regardless of endpoint, should follow the same shape. Agents build internal models of what to expect. Surprise response structures break those models.

// Success
{
  "data": { ... },
  "meta": {
    "request_id": "req_123",
    "timestamp": "2026-04-27T10:00:00Z"
  }
}

// Error — every error looks the same
{
  "error": {
    "code": "user_not_found",
    "message": "No user with ID usr_123 exists",
    "retryable": false,
    "docs_url": "https://docs.example.com/errors/user_not_found"
  }
}

Never return different shapes for the same endpoint depending on state. Agents can't handle conditional response structures reliably.

Idempotency

Agents retry. Networks fail. Operations get called twice. Your API needs to handle this without creating duplicate records, duplicate charges, or duplicate emails.

POST /payments
Idempotency-Key: pay_abc123

Same key, same result every time, regardless of how many times the agent calls it. The agent doesn't need to track whether the call succeeded. It retries safely and trusts the server to dedupe.

Semantic error codes

Generic HTTP status codes aren't enough. An agent receiving a 400 needs to know exactly what went wrong and what to do about it.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You have exceeded 100 requests per minute",
    "retryable": true,
    "retry_after": 45,
    "docs_url": "https://docs.example.com/errors/rate_limit_exceeded"
  }
}

Error codes should be:

Machine-readable strings, not just numbers
Stable: never change them once published
Documented with recommended recovery actions
Categorized: auth errors, validation errors, rate limits, server errors

Pagination that works at scale

Agents process large datasets. Cursor-based pagination is better than offset because it's stable. Inserting new records doesn't shift results mid-traversal.

{
  "data": [...],
  "pagination": {
    "next_cursor": "cur_abc123",
    "has_more": true
  }
}

Rate limiting with transparency

Agents are fast and don't naturally pace themselves. Return rate limit state in every response so agents can self-regulate before hitting limits.

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1714215600
Retry-After: 45

Webhooks over polling

Agents shouldn't poll. For operations that take time, use webhooks and give the agent a job ID to reference when the webhook fires.

// Immediate response
{
  "job_id": "job_abc123",
  "status": "processing"
}

// Webhook when complete
{
  "event": "job.completed",
  "job_id": "job_abc123",
  "result": { ... },
  "timestamp": "2026-04-27T10:05:00Z"
}

2. MCP — making your product callable

Model Context Protocol is the new integration layer between AI coding tools and external services. Without an MCP server, agents have to parse your docs and construct API calls from scratch every time. With one, your product becomes a first-class tool that agents can discover and call through natural language. Headless APIs were already designed for programmatic consumption; MCP adds the discoverability layer they were missing.

When Clerk shipped their MCP server, a developer using Claude Code could say "add authentication to this Next.js app" and Claude called Clerk's APIs directly. No copy-pasting from docs, no configuration errors, no context switching.

What an MCP server does

An MCP server wraps your API and exposes it as a set of tools. It handles:

Tool discovery, so the agent asks what your product can do and gets a structured list
Parameter validation before the API call is made
Response formatting into something the agent can reason about
Error handling with actionable messages

Basic MCP server structure

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { name: "your-product-mcp", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_user",
      description: "Retrieve a user by their ID. Returns the user's profile including email, name, created date, and subscription status. Use this before performing any action that requires knowing the user's current state. Returns null if the user does not exist — check for this before proceeding.",
      inputSchema: {
        type: "object",
        properties: {
          user_id: {
            type: "string",
            description: "The unique identifier of the user (e.g., usr_abc123)"
          }
        },
        required: ["user_id"]
      }
    }
  ]
}));

Tool description is everything

The description field is where most MCP implementations fail. Agents use it to decide when and how to call the tool. A weak description means the agent calls the wrong tool at the wrong time or passes the wrong parameters. This is one of the harness-level mistakes that breaks agents before any model upgrade can help.

Bad:

"Gets a user"

Good:

"Retrieve a user by their ID. Returns the user's profile including email, name,
created date, and current subscription status. Use this before performing any
action that requires knowing the user's current state. Returns null if the user
does not exist — check for this before proceeding."

The description should tell the agent what the tool does, when to use it, what it returns, and edge cases to watch for.

What to expose in your MCP server

Not everything in your API needs to be an MCP tool. Start with the actions developers perform most often and the ones that are most error-prone when done manually. Auth flows, resource creation, and configuration are high value. Internal admin operations, bulk data exports, and rarely used endpoints can wait.

3. Documentation — built for machines and humans

Documentation in the agentic era has to serve two audiences. A human developer evaluating your product needs narrative, context, and examples that tell a story. An AI agent needs structured, machine-readable specifications it can parse and act on.

Most developer tool docs were built for humans only. That worked when humans were the ones doing the integration. It doesn't work anymore.

OpenAPI spec — the machine-readable foundation

A well-maintained OpenAPI spec is the minimum requirement. Agents use these to understand your API surface without reading prose.

paths:
  /users/{id}:
    get:
      summary: Retrieve a user by ID
      description: >
        Returns a single user object. Use this endpoint when you need to look up
        a specific user's details before performing an action. Returns 404 if the
        user does not exist — always handle this case before proceeding.
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the user
          schema:
            type: string
            example: usr_abc123
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              example:
                id: usr_abc123
                email: luke@example.com
                created_at: "2026-01-01T00:00:00Z"
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

Critical requirements:

Every endpoint documented with description, parameters, request body, and response schemas
Examples on every parameter and response
Error codes enumerated with meanings, not just HTTP status codes
Keep the spec in sync with the actual API. Stale specs break agents and erode developer trust

Copy-to-install examples

Shadcn-style copy-to-install patterns have become the standard for a reason. Developers and agents both gravitate toward examples they can paste directly and have working in under a minute. Every quickstart should have this pattern.

# Install
npm install @your-product/sdk

# Configure
export YOUR_PRODUCT_API_KEY=sk_live_abc123

# First API call

import { YourProduct } from '@your-product/sdk'

const client = new YourProduct({ apiKey: process.env.YOUR_PRODUCT_API_KEY })

const user = await client.users.get('usr_abc123')
console.log(user.email)

One install command. One config step. One working call. If your quickstart takes more than that, you're losing developers and agents at the starting line.

Keeping docs current

Stale documentation is worse than no documentation for agents. A human notices when docs don't match behavior. An agent acts on what the docs say and produces bugs that are hard to trace.

This means:

Docs as code, with documentation living alongside the codebase and updated in the same PR
Automated API reference generation from the OpenAPI spec, so nobody updates API references by hand
Changelogs that call out breaking changes explicitly with migration paths
Versioned documentation when you have multiple API versions active

Error documentation that enables recovery

Most products document happy paths well and error paths poorly. Agents hit error paths constantly. Every error code should have a dedicated doc page that explains what caused it and exactly how to recover.

Error: rate_limit_exceeded
Cause: You have made more than 100 requests per minute
Recovery: Wait for the retry_after value in the response header, then retry the request
Prevention: Implement exponential backoff and respect the X-RateLimit-Remaining header

4. Developer experience — reducing friction at every step

The best API in the world loses to a worse API with better DX. This was true before AI agents and it's still true now. The difference is that agents amplify both good and bad DX. They'll use a well-designed SDK flawlessly and get stuck in the same confusing flows that trip up humans.

SDKs that match how developers work

Generate your SDKs from your OpenAPI spec. Don't handwrite them. Handwritten SDKs drift from the API and introduce inconsistencies. Generated SDKs stay in sync automatically.

A well-designed SDK should:

Match the structure of the API without adding abstraction that obscures what's happening
Include TypeScript types for everything
Surface errors in a way that makes them easy to handle
Work with the frameworks your customers actually use: Next.js, Express, FastAPI, not just vanilla HTTP

Framework-specific quickstarts

A generic quickstart is less useful than a Next.js quickstart, a FastAPI quickstart, and a Rails quickstart. Developers work within frameworks, not in the abstract. The faster you can get someone from install to working implementation in their stack, the more likely they adopt.

Stripe does this well: separate quickstarts for Next.js, Rails, Flask, and more. Each one is tailored to how that framework handles payments, not a generic HTTP example with a note to adapt it.

Interactive examples and playgrounds

API playgrounds where developers can make calls without setting up an account lower the evaluation barrier. Agents can also use these to test calls before embedding them in code.

5. Authentication and permissions for agents

This is where most developer tools are least prepared for the agentic era. Human auth is designed for sessions: you log in, you stay logged in. Agent auth needs to be granular, short-lived, auditable, and revocable per task.

Scoped API keys

Never give agents a master API key. Give them a key scoped to exactly what they need for a specific task.

// Too broad — agent can do anything
API_KEY: sk_live_abc123 (full access)

// Better — agent can only read users and create orders
API_KEY: sk_live_xyz789 (scope: users:read, orders:write)

OAuth for agent delegation

When an agent acts on behalf of a human user, OAuth is the right pattern. The agent gets a token scoped to that user's permissions. It can't do anything the user couldn't do themselves.

POST /oauth/token
{
  "grant_type": "client_credentials",
  "client_id": "agent_abc123",
  "client_secret": "sk_agent_xyz789",
  "scope": "orders:read orders:write"
}

The token comes back scoped to exactly what the agent requested:

{
  "access_token": "tok_abc123",
  "scope": "orders:read orders:write",
  "expires_in": 900
}

Short-lived tokens

Agent tokens should expire quickly. A human session might last 30 days. An agent token for a specific task should last minutes to hours. This limits the blast radius if a token is compromised.

Audit logging

Every agent action should be logged with enough context to answer: who authorized this, what did the agent do, when, and why. Enterprise customers will not buy without it.

{
  "event": "order.created",
  "actor": {
    "type": "agent",
    "id": "agent_abc123",
    "acting_for": "usr_xyz789"
  },
  "resource": {
    "type": "order",
    "id": "ord_def456"
  },
  "timestamp": "2026-04-27T10:00:00Z",
  "request_id": "req_ghi789"
}

6. Agent skills — teaching agents how to use your product

Beyond MCP, some platforms are building agent skills: structured context that AI coding tools load before working with your product. Where MCP lets agents call your API, skills teach agents how to use your API well.

Clerk's agent skills embed authentication knowledge directly into Claude Code and Cursor. When a developer adds the Clerk skill, the AI already knows the full API surface, common patterns, which approach to use for which use case, and current examples that match the latest API version.

# clerk-auth-skill.md

## When to use Clerk
Use Clerk when the project needs authentication and the framework is
Next.js, Remix, or Astro. Do not use Clerk for server-only APIs
without a frontend.

## Setup pattern
Always use the App Router integration for Next.js 13+.
Never use the Pages Router integration for new projects.

```tsx
// middleware.ts — always create this first
import { clerkMiddleware } from '@clerk/nextjs/server'
export default clerkMiddleware()
export const config = {
  matcher: ['/((?!.*\\..*|_next).*)', '/', '/(api|trpc)(.*)'],
}
```

## Common mistakes
- Don't wrap the entire app in ClerkProvider if you only need auth
  on specific routes
- Don't use useAuth() in server components. Use auth() instead
- Don't store Clerk user IDs as your primary user identifier.
  Sync to your own database on signup

This is what agents need that documentation alone doesn't provide: opinionated guidance on when to use what, which patterns to avoid, and decision logic that prevents the mistakes developers hit most often. Documentation tells an agent what your API can do. A skill tells it what your API should do in a specific context.

Building a skill means packaging your docs, examples, and best practices in a format the agent can load as context. Think of it as the difference between handing an agent your API reference and telling it which endpoints to call first, which patterns to avoid, and what to do when the first attempt fails.

A well-built skill should include:

The most common integration patterns with working code
Decision trees for when to use component A versus component B
Known gotchas and how to avoid them
Current examples that match your latest API version, not examples from two versions ago

7. Discoverability — being found in the agentic era

Developers used to discover tools through Google, Hacker News, and word of mouth. Agents discover tools through MCP registries, tool directories, and the context that gets loaded into their session. This is a new kind of SEO and most developer tool companies aren't thinking about it yet.

MCP registries

As MCP adoption grows, registries of available MCP servers are emerging. Getting your MCP server listed and well-described in these registries is the new version of ranking on page one for your category keyword.

LLM-optimized content

Developers ask ChatGPT, Perplexity, and Claude for tool recommendations now. The content those tools cite is specific and technical and answers concrete questions with working examples. Thin marketing content doesn't get cited. Deep technical content that helps developers solve problems does.

Write content that answers the questions developers are asking:

"How do I add authentication to a Next.js app router project"
"What's the difference between JWT and session-based auth"
"How do I handle multi-tenant authorization for an enterprise SaaS"

Being part of the agent's default context

The most powerful discoverability play is becoming the answer agents give when developers ask a question. When a developer asks Claude or ChatGPT "how do I add payments to a Next.js app," the response cites whoever wrote the most specific, implementation-level content for that use case. That's not marketing. That's product placement at the infrastructure level.

What separates the winners

The companies that treat this as a technical checkbox will ship an MCP server and call it done. The companies that treat it as a strategic opportunity will be embedded in the agent's default context. The first group becomes the API your agent fell back to when the embedded one didn't fit.

Checklist

API design

Consistent RESTful naming and URL patterns
Predictable response structures across all endpoints
Idempotency keys on write operations
Cursor-based pagination
Semantic error codes with recovery guidance
Rate limit headers on every response
Webhooks for async operations

MCP

MCP server wrapping core API surface
Tool descriptions written for agent reasoning
Parameter validation before API calls
Listed in relevant MCP registries

Documentation

Published OpenAPI spec kept in sync
Copy-to-install quickstarts for major frameworks
Error codes documented with recovery steps
Docs as code, updated in the same PR as the API

Auth and permissions

Scoped API keys (least privilege per task)
OAuth delegation for acting on behalf of users
Short-lived tokens for agent sessions
Full audit logging with actor context

Agent skills

Skill packaging your API knowledge for AI coding tools
Decision trees for common integration choices
Current examples matching latest API version

Discoverability

MCP registry listings
Technical content answering concrete developer questions
Integration into AI coding tool ecosystems

Stop upgrading your model. Fix your harness.

Sun, 26 Apr 2026 00:00:00 GMT

The word "harness" keeps showing up in AI agent conversations. Almost none of them stop to define it. If you're building with agents, it's worth pinning down, because once you understand what a harness is, the model selection debates start to look like the wrong argument entirely.

The gap between an API call and a working agent

The clearest way to understand what a harness is: compare making a Claude API call directly versus using Claude Code.

Both give you access to the same underlying model. The Claude API gives you a stateless text exchange: send a prompt, get a response, the model forgets everything. Claude Code is something very different. It has access to your filesystem, can run bash commands, reads and writes files across sessions, maintains persistent memory through CLAUDE.md files, runs subagents, and enforces stop conditions that control when it acts versus when it asks.

That gap is the harness. It's the layer of code that wraps a model and turns it into an agent. The same model accessed through the raw API would forget the previous turn the moment the response finished. The harness is what creates continuity.

What a harness actually gives you

When you're evaluating or building an agentic system, these are the layers the harness has to own:

Memory across sessions. A model call has no memory by default. The harness decides what context gets injected at the start of every session, what gets written back at the end, and how accumulated knowledge is stored between runs. In Claude Code, this is file-based. CLAUDE.md files sit in your project directory, readable and editable by you.

Tools. Not in the abstract sense, but the specific operations the agent can execute: reading files, running shell commands, calling APIs, searching the web, writing to a database. The harness defines the tool surface area. A narrow tool surface produces a more predictable agent; a wide one produces a more capable one. Getting that tradeoff right is a harness decision, not a model decision.

State that survives across a task. Complex tasks don't fit in a single context window. The harness has to manage what gets preserved when a session ends, what gets summarized and compressed, and what gets discarded. This is one of the harder engineering problems in agentic systems, and most implementations either ignore it or handle it poorly. The symptom is an agent that loses the thread midway through a long task.

Guardrails that actually run. When does the agent stop and ask a human? What happens when it detects it's looping? Which tools require explicit approval before the agent uses them? These policies can be written into prompts, but prompt-level guardrails drift. The harness enforces them deterministically, at the architecture layer, not through instructions the model can reason around.

Why harness design beats model selection

The default assumption when an agent underperforms is to upgrade the model. That's almost never the right first move.

Every tool in this space pitches some version of the same thing: better orchestration, smarter routing, more specialized agents. The problem is almost always scaffolding quality: how context is managed, how memory passes between agents, whether the tool surface fits the task. Adding more layers doesn't fix that. I keep a running list of what I've tried on my tools page if you want to see what's worth looking at.

Before switching models, check these four things.

System prompt length. A 450-line system prompt produces measurably worse behavior than a 100-line one with real examples. Vague instructions at scale fragment attention.

// Too long
You are a helpful assistant that assists with many tasks. You should always
be polite and professional. When answering questions, consider all angles.
Make sure to be thorough but also concise. Never make assumptions. Always
ask for clarification when uncertain. Format responses clearly...
[400 more lines of vague instructions]

// Tight
You are a code reviewer. Flag bugs, security issues, and style violations.
Return JSON: {"issues": [{"line": number, "type": string, "message": string}]}
Example: {"issues": [{"line": 42, "type": "security", "message": "SQL injection risk"}]}

A short prompt with a concrete example outperforms a long one with descriptive rules.

Context management. Without compaction, long tasks degrade as older turns crowd out what the agent needs to act on now.

// Unmanaged
messages.push({ role: "assistant", content: fullResponse });

// Managed
if (tokenCount(messages) > 80000) {
  messages = [summarizeOlderTurns(messages.slice(0, 10)), ...messages.slice(10)];
}

Most agent failures on long tasks aren't model failures. They're context failures.

Tool descriptions. The model decides whether to use a tool based on its description. Vague descriptions produce inconsistent tool use.

// Vague
{ name: "bash", description: "Runs bash commands." }

// Useful
{ name: "bash", description: "Runs shell commands. Use to execute code, read file contents, or verify system state. Do not use for string operations you can handle directly." }

The description should tell the model not just what the tool does, but when to reach for it.

Stop conditions. An agent without stop conditions runs until it hits a hard limit, and output quality degrades the longer it runs unchecked.

// No stop condition
while (true) {
  response = await agent.run(task);
}

// Explicit stop
for (let attempt = 0; attempt < maxAttempts; attempt++) {
  const response = await agent.run(task);
  if (["complete", "failed"].includes(response.status)) break;
  if (detectLoop(response, history)) throw new Error("Agent is repeating steps");
}

Loop detection and a max attempt ceiling are the minimum. Most production failures come from agents that didn't know when to stop.

If any of those have bad answers, fixing them will do more than upgrading to the next model tier.

Claude vs OpenAI: where the harness differences actually show up

Once you've got the harness fundamentals right, model selection still matters, just less than most people think. Here's where Claude and OpenAI differ for developers building harnesses.

Prompt caching. Your system prompt (the persistent context, memory injections, tool definitions) is often identical across hundreds or thousands of agent turns. Claude's prompt caching lets you cache that block and pay roughly 10% of the normal input token cost on cache hits.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 8096,
  system: [
    {
      type: "text",
      text: persistentContext,
      cache_control: { type: "ephemeral" }
    }
  ],
  messages: [{ role: "user", content: task }]
});

cache_control marks the system prompt for caching. Subsequent calls with the same prompt pay ~10% of the normal input token cost.

For a harness running hundreds of agent turns per hour, the savings add up fast. OpenAI's Responses API achieves something similar through server-side state, but through different mechanics and with different portability implications.

Reasoning control. Before a model responds, it can think through a problem internally: working out steps, checking assumptions, considering edge cases. That internal process is reasoning, and it costs tokens. Claude exposes it as a configurable parameter. On Opus 4.7, reasoning is adaptive (the model decides how much to think based on the task rather than consuming a fixed budget).

const response = await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 16000,
  thinking: {
    type: "adaptive"
  },
  messages: [{ role: "user", content: task }]
});

type: "adaptive" tells Claude to decide for itself how much reasoning the task needs. You're not paying for max reasoning on every turn.

Claude also exposes effort levels (low, medium, high, xhigh, and max) as a coarser control knob. Opus 4.7 added xhigh between high and max. This matters for harness design because you can tune reasoning intensity per task type: lighter effort for routine operations, heavier for complex debugging or multi-file refactors, rather than running everything at the same cost.

OpenAI routes reasoning internally and doesn't expose direct control over it. With Anthropic, you set effort per task. With OpenAI, the model decides for itself.

Tool instructions. How you write tool instructions has a larger effect on agent behavior than most people expect. Capable models will often think through a problem before reaching for a tool, which is usually what you want. But it means your harness needs to be explicit about when tool use is required rather than optional:

// Too vague
Check whether the API endpoint returns the correct schema.

// Explicit
Use the read_file tool to open schema.json, then use the bash tool
to run the test suite and verify the output matches that schema.

The first leaves the agent to decide whether to act. The second names the tools, the files, and what to check.

This principle extends to running subagents (separate agent instances your harness kicks off to handle tasks in parallel). If your harness depends on that parallel execution across multiple files or items, specify it explicitly. Don't assume the model will split the work on its own.

The memory question nobody asks early enough

Switching models is easy. The APIs are similar enough that moving from Claude to GPT or back is a few hours of work. Models are stateless (each request starts fresh with no memory of previous interactions), so there's nothing accumulated to lose.

Memory is different. Once an agent has built up context over weeks or months, your codebase conventions, your debugging patterns, how you prefer things structured, that accumulated state is doing the actual work. The same setup without the memory produces a noticeably worse agent. If that memory lives somewhere you don't control, you can't take it with you.

Claude Code's memory is file-based. CLAUDE.md files, project notes, session summaries all live in your filesystem. You can read them, edit them, commit them to git, and inspect exactly what the agent knows about your project. When a long session gets compacted, the summary goes into a file.

I think about this the same way I think about using Obsidian for my own knowledge management. Notes in Markdown files I own, stored locally, not locked in a platform I'm renting. The agent equivalent is the same idea. Intelligence that accumulates in your filesystem, not theirs. A second brain you actually control.

OpenAI's Codex generates compaction summaries that are encrypted and not portable outside the OpenAI ecosystem. Whatever context your agent accumulates stays in their infrastructure.

Before you commit to any agent tool for production use, ask:

Where does state actually live, and do I own those files?
What survives session compaction, and what gets lost permanently?
Are compaction summaries readable, or are they opaque?
If I switched providers in a year, could I take the agent's accumulated context with me?

Most people don't ask this until they're already paying the switching cost. By then the answer usually isn't good.

Pick your model. Own your memory.

Anthropic, OpenAI, Google, and several open-weight teams are all shipping capable models on short release cycles. That's not going to thin out. It means model selection will stay a decision, just a narrow one. The distance between the top model options is smaller than the distance between a well-engineered harness and a poorly engineered one.

Switching the model is a small change. The context your agent builds up over months is what's hard to replace: how your codebase is structured, how you like things handled, what to skip. Keep it in files you own.

For deeper coverage of where current models stand on benchmarks and pricing, see the AI Models Guide.

Is headless making a comeback?

Tue, 17 Mar 2026 00:00:00 GMT

Headless had its moment around 2018-2021. Contentful handled content, Shopify's Storefront API handled commerce, Stripe handled payments, and Auth0 handled identity. The pitch was the same everywhere: here's a powerful API, build whatever frontend you want on top of it.

The architecture made sense. The problem was that every headless tool required significant engineering investment to set up and maintain. Not just "hook up an API" investment, but "build a frontend, design a content model, configure preview environments, and own the deployment pipeline" investment. Most companies didn't have the engineering bandwidth to treat their CMS or commerce layer like a custom software project. And the ones that did often couldn't justify keeping a developer on it long-term once the initial build was done.

What headless actually cost you

The API-first model works well when you have engineers who treat these services like product infrastructure. When you don't, you get content teams staring at JSON editors and marketing waiting on engineering to change a checkout flow.

The headless CMS space is where this played out most visibly. Contentful started bolting on visual editing tools and composable page builders. Strapi added a content-type builder. Sanity shipped Sanity Studio with customizable desk structures. Every headless CMS slowly crept toward becoming a Digital Experience Platform, rebuilding the same workflows and interfaces they were supposed to eliminate.

The same pattern showed up in commerce. Shopify's headless Storefront API gave you full control, but building a custom storefront meant maintaining a React app, handling cart state, managing checkout flows, and syncing inventory. Most merchants went back to Shopify themes because the operational cost of maintaining a custom storefront wasn't worth it without dedicated engineering.

Headless vendors spent years telling you to decouple everything through APIs, then spent the next few years rebuilding the interfaces and workflows that monolithic tools already had. Non-technical users couldn't operate these systems independently, so the vendors built the interfaces back in. The result was headless architecture with monolithic complexity.

Visual development ate headless for lunch

Visual development tools showed up and solved a different problem: letting non-developers build and ship without waiting on engineering.

Tools like Webflow, Builder.io, and Framer gave marketing teams direct control over pages, layouts, and content without requiring a pull request. Builder.io went further by offering visual editing on top of existing codebases, a hybrid model where developers own the system and marketers own the pages.

Visual development grew while pure headless adoption slowed outside of enterprise. The hybrid approach (visual editing backed by APIs) turned out to be what most teams needed. You got the content API when you wanted it and a visual editor when you didn't want to bother engineering.

Headless started feeling like an architecture for teams with more developers than they knew what to do with. For everyone else, it was overhead.

Then LLMs learned to talk to APIs

Large language models can build working applications. But the more consequential thing they learned to do is talk to existing APIs and operate services through them.

This is what MCP (Model Context Protocol) made repeatable. You give an LLM access to a set of API tools, a CMS, a commerce platform, a payment processor, an analytics service, and it can read, create, update, and query through those APIs using natural language. No SDK wrappers to write. No frontend to build. You describe what you want, the model figures out the API calls, and the work gets done.

MCP isn't without its critics. Perplexity recently announced they're moving away from MCP internally in favor of their own Agent API, citing token overhead and authentication friction at scale. Those are real problems. But the pattern MCP established, LLMs operating through APIs via standardized tool definitions, is already showing up through function calling and agent APIs regardless of whether MCP itself becomes the long-term standard.

Sanity is a good example of this. Their content lake API is structured, their schemas are typed, and an LLM connected to Sanity can create documents, update fields, manage assets, and publish content through conversation. The same workflow that used to require a developer writing a custom integration now takes a .json tool definition and an API key.

This isn't limited to CMS. Any well-documented API with token-based auth works the same way. Stripe's API is so well-structured that models can create payment links, pull transaction data, and manage subscriptions through it. Shopify's Storefront and Admin APIs follow similar patterns. The developer who used to sit between the business team and the API? A model that already read the docs can do that job now.

You secure your API keys and set permissions like you always would. But the person using the system doesn't need to understand REST semantics or write fetch calls. They describe what they want, and the model handles the translation.

The developer dependency is dissolving

The core objection to headless was always operational, not architectural. Nobody argued that APIs were the wrong approach. The argument was always: "Sure, but who's going to build and maintain all of this?"

That was a fair objection when building meant writing React components, setting up preview environments, configuring webhooks, and debugging deployment pipelines. It's less of one when building means opening Claude Code and saying "set up a Next.js frontend that pulls content from our Sanity project and deploys to Vercel." Or "create a Shopify storefront with these products and connect Stripe checkout."

The developer's role shifts from implementation to architecture. You still need someone to design the data model, set up the deployment pipeline, and make security decisions. But the day-to-day work of building interfaces, managing data through APIs, and wiring services together? That's moving to the LLM, working through the API layers that headless tools already built.

Companies like Stripe, Shopify, and Sanity spent years building well-structured APIs, thorough documentation, and typed schemas. They did that work to support developer integrations. It turns out those same qualities (structured, documented, typed) are exactly what makes an API easy for an LLM to use. Every headless tool that invested in API quality accidentally built infrastructure that LLMs can now operate.

The stack I'm thinking about

Headless APIs (Sanity, Stripe, Shopify, Algolia, Clerk) as the service layer. An agentic coding tool (Claude Code, Cursor) as the builder. A frontend framework (Next.js, Astro) as the delivery layer. MCP or function calling as the bridge between the LLM and the APIs.

The team describes what they need, the LLM builds it through the APIs, and the developer reviews and maintains the architecture. Each service stays in its lane: Sanity handles content, Stripe handles payments, Algolia handles search.

I've used Claude Code connected to Webflow's CMS API through MCP to create and manage content programmatically. The experience is closer to pair programming with someone who already read the API docs than it is to traditional service administration. And every headless tool with a decent API is a candidate for this same workflow.

There's another layer to this. When a builder asks Claude Code or Cursor to build a newsletter, the model suggests specific APIs like Resend for email and gives a recommended option. Headless services aren't just competing for mindshare anymore, they're competing for LLM recommendations. How you show up in those suggestions matters, whether that's through llms.txt, AEO (Answer Engine Optimization), or having the cleanest docs and SDK in your category. Being one of the three options the model suggests is starting to matter the way ranking on the first page of Google used to.

What still needs to be true

This only works if the headless service has a well-designed API. Sanity's content lake API is structured and predictable, with typed schemas that an LLM can query and write to after seeing a few examples. Stripe is the gold standard here with consistent naming, thorough docs, and predictable error formats.

Where this breaks down:

Undocumented edge cases - LLMs can only work with what's documented. If publishing requires a specific sequence of API calls that isn't in the docs, the model will get it wrong.
Complex permissions models - Multi-tenant setups with role-based access and environment-specific publishing rules add friction that conversational interfaces don't handle gracefully.
Asset management - Image uploads, transformations, and CDN invalidation involve binary data handling that's harder to do through natural language than CRUD operations on text content.
Preview workflows - Showing unpublished content in context still requires frontend infrastructure. An LLM can create the content, but previewing it on a staging site is a deployment problem, not an API problem.

These explain why this isn't a "headless is fully back" story yet. It's closer to "headless lost for the wrong reasons, and those reasons are disappearing."

Headless lost a battle it might win retroactively

Visual development tools won because they removed the developer dependency for content operations. That was the right answer in 2022. But visual development still comes with tradeoffs. Proprietary rendering, platform lock-in, and a ceiling on what you can build before you need custom code. Most visual tools have APIs and integrations, but they're secondary to the canvas.

Headless architecture doesn't have those constraints. It's APIs and data structures that you can move between frameworks, host anywhere, and compose however you want. Non-developers could use it, but the moment they wanted something different from the initial build, the developer tickets started piling up.

LLMs and agentic building tools are filling that gap. The complexity of headless doesn't disappear, but it becomes something you can work through in conversation instead of code. The APIs and data models don't change. Who can operate them does.

I don't think the future is headless vs. visual. I think it's both, and the line between them is blurring. The platforms that treat their APIs as an afterthought are going to lose ground to the ones that invest in them. When an LLM can operate a CMS, a commerce API, and a payment processor through conversation, the visual editor becomes one interface among several, not the only way in.

And if that's right, a lot of companies that consolidated back to monolithic platforms in 2023 might be rethinking that decision.

End of coding, age of building

Sat, 07 Mar 2026 00:00:00 GMT

The constraint moved. For decades, the thing that determined whether software got built was whether someone could write the code. You needed syntax, framework knowledge, years of pattern recognition. That's not the constraint anymore. The constraint is whether you can describe what you want built, evaluate what comes back, and make good decisions about what to do next.

This didn't happen gradually. A set of tools crossed a threshold within about six months, and the gap between "I have an idea" and "I have a working prototype" collapsed from weeks to hours.

What happened in late 2025

The shift wasn't one tool getting better. It was five or six things converging at once.

Cursor shipped background agents in late 2025, letting multiple AI processes work across a codebase simultaneously. One agent refactors your auth layer while another writes tests for the module you just finished. Parallel execution against a shared codebase, with conflict resolution built in. That's a different editing model than autocomplete.

Anthropic released Opus 4.5 and a generation of RLVR-trained models that crossed a reasoning threshold. Earlier models could write functions. These models could hold architectural context across a 50-file project, understand why a particular abstraction existed, and make changes that respected the existing design. The gap between "generates code" and "understands the codebase" closed.

Claude Code started running as a local CLI, reading your file system, running your tests, iterating on failures without round-tripping through a browser. It turned a chat interface into something closer to a junior developer sitting next to you, except it could work through an entire debugging session in minutes.

And the browser-based builders matured. Bolt, Lovable, and v0 went from generating impressive demos to generating deployable applications. Not always clean applications. Not always production-grade. But working software that a non-developer could ship to real users, connected to real databases, with real authentication flows.

Each of these alone was incremental. Together, they moved the floor.

The coding era versus the building era

The coding era rewarded a specific set of skills. You needed to know that JavaScript handles async differently than most languages, that React re-renders on state change, that SQL joins have performance implications at scale. Years of practice built an intuition for debugging, architecture, and language-specific idioms. The work was writing code, and the quality of the code depended on your accumulated experience writing it.

The building era rewards a different set. Articulation matters more than syntax. Can you describe the data model clearly enough that an AI generates the right schema? Do you know that this feature needs async processing instead of a synchronous call, even if you've never wired it up yourself? And when the AI generates three approaches, can you tell which one breaks at scale? The skills shifted from implementation to specification and evaluation.

The difference shows up in specific scenarios. A marketing ops manager needed an internal tool to sync campaign data between HubSpot and their reporting dashboard. In the coding era, that's a ticket in Jira, a sprint planning conversation, two weeks of developer time. In the building era, she described the sync logic to Claude Code, iterated on the output for an afternoon, and had a working tool by end of day. Because the constraint moved from implementation to specification.

A designer prototyping a dashboard in Figma used to hand off static mockups to a frontend team. Now the prototype becomes the product. v0 takes the design, generates the React components, and the designer iterates on the actual code output. The handoff didn't get faster. The handoff disappeared.

Who builds now

The audience expanded, but not in the way the "everyone is a developer" crowd claims. A product manager shipping an internal tool isn't a developer. A designer generating React components from a prototype isn't a frontend engineer. They're building software, but they're doing it through a different interface than a code editor and a terminal.

The people making product decisions can now execute on them directly. That's the actual shift. A domain expert who understands the problem space deeply can build the first version of a solution without translating their knowledge through a development team. The translation layer got thinner.

Developers didn't become less important. They became faster. A senior engineer using Cursor with background agents can move through a codebase at a pace that wasn't possible two years ago. The tedious parts shrink. The judgment parts stay. A staff engineer reviewing AI-generated code still needs to spot the subtle concurrency bug, the missing index, the abstraction that will break when requirements change. That work didn't go anywhere.

What this means for developer content

If you're writing tutorials that start with "First, install the SDK and initialize a client," you're writing for a shrinking audience. Not shrinking to zero, but narrowing. A growing segment of builders thinks in prompts, not imports. They describe what they want, evaluate the output, and iterate. The SDK installation happens inside that loop, handled by the AI, often without the builder knowing which package manager ran.

This doesn't mean content gets dumber. It means the frame shifts. Instead of "How to implement authentication with NextAuth," the useful article becomes "How to think about authentication for a SaaS app." What are the tradeoffs between session-based and token-based auth? When does OAuth make sense versus magic links? What are the actual security implications of each choice?

The content that holds value is the content that helps someone make decisions, not the content that walks them through keystrokes. Implementation guides aren't dead, but they're commoditized. The AI can generate a NextAuth setup. What it can't do is tell you whether NextAuth is the right choice for your specific situation.

What didn't change

Architecture decisions still require someone who understands distributed systems and scaling characteristics. AI can generate a microservices setup, but it doesn't know whether your team of four should be running microservices or a monolith. It doesn't know your deployment constraints, your on-call rotation, or the operational complexity your team can absorb.

Judgment still matters. AI generates plausible code quickly. It also generates plausible bugs quickly. Someone needs to review the output, understand the failure modes, and catch the cases where the AI optimized for the wrong thing. A function that passes all tests but handles errors by swallowing them silently is worse than a function that doesn't compile, because at least the compiler error is honest.

Senior developers aren't less valuable. They're more leveraged. The gap between a senior engineer with AI tools and a junior engineer with AI tools is wider than the gap was without AI. The senior knows what to ask for and knows when the output is wrong. The ceiling didn't move. The skills that make senior engineers valuable are the same ones AI can't replicate.

The career path question

Here's the part nobody has a good answer for: what does a junior developer career path look like when the entry-level work is automated?

Junior roles traditionally existed as training grounds. You wrote CRUD endpoints, fixed CSS bugs, added form validation. Those tasks built intuition for how systems work, how code breaks, and how to debug when something doesn't behave. That intuition feeds the judgment that makes senior engineers valuable. The entry-level work wasn't just work. It was education.

If AI handles the CRUD endpoints and the form validation and the CSS bugs, the question isn't whether juniors are needed. It's how they develop the judgment that AI can't replace. The obvious answer is "they'll learn by reviewing AI output instead of writing code from scratch." Maybe. But reviewing code you don't fully understand is a different skill than writing it, and it's not clear it builds the same depth of understanding.

This is an open question, and I don't think anyone has an honest answer yet. The tools moved faster than the career structures adapted. Companies are still hiring for roles defined by the coding era while the work increasingly belongs to the building era. That mismatch will resolve, but how it resolves will shape the next generation of engineers.

What is developer marketing and why it exists

Mon, 02 Feb 2026 00:00:00 GMT

Developer marketing sits at the intersection of product marketing and growth marketing. You’re responsible for launches, messaging, and positioning, but also for how those decisions show up in campaigns, GTM, and adoption. The role owns the developer persona end to end and is accountable for both product-led and sales-led growth, not just shipping something.

The role runs in parallel with most marketing functions, from content and lifecycle to web, demand gen, and RevOps. The scope doesn’t stop at signups. You’re responsible for the full funnel, which means accounting for revenue, not just activation. If people sign up but deals don’t close, that’s still a problem to solve.

You’re also more technical than the average marketer. You’re closer to the product, the workflows, and the constraints, and you put developer trust first. Once that trust is lost, it’s hard to recover.

That combination is what makes developer marketing both exciting and difficult. The role comes with overlap, ambiguity, and frequent justification, especially in developer-first companies where everyone speaks developer and ownership is rarely clean.

Why this role exists at all

Most marketing is optimized to explain value at a high level. That breaks down when claims have to hold up under actual usage. Developers evaluate through workflows and constraints, and they notice quickly when something doesn’t.

Developer marketing exists because this kind of evaluation requires technical judgment before messaging ships. Someone has to pressure-test positioning against how the product actually behaves. Someone has to surface mismatches early, before they turn into sales friction, support tickets, or churn that no one planned for.

When that responsibility is missing, the gaps don’t disappear. They just move downstream, where they’re harder and more expensive to fix.

Why developer-first companies make the role harder to see

In companies built primarily for developers, developer context is everywhere. Marketing teams tend to be more technical and already speak to developers without translation. There’s a shared baseline for how developers think.

In those environments, developer marketing doesn’t always show up as a clearly defined function. The work spreads across teams. Parts of it live in product. Parts live in content, growth, or demand gen.

That’s where confusion starts. Not because the role isn’t needed, but because responsibility is diffused. Everyone contributes. No one is clearly accountable for how the product is framed and evaluated by developers end to end. The role doesn’t disappear in developer-first companies. Accountability just becomes harder to pin down.

Why technical chops matter more than familiarity with developers

There’s a difference between being adjacent to developers and having technical judgment. The first gives exposure and the second lets you evaluate whether something will hold up once it’s actually used.

Developer marketers need to be able to read content and recognize when something is glossed-over. They need to look at a demo and tell whether it actually holds up. They need to understand why a limitation matters before customers encounter it and turn it into a problem.

This isn’t about writing production code every day. It’s about understanding systems well enough to evaluate claims honestly. Familiarity with developer culture helps, but technical fluency is what makes the role effective.

What developer marketing is responsible for

Developer marketing is responsible for maintaining clarity and credibility with a technical audience, even when ownership across teams is messy.

In practice, that responsibility tends to show up in a few places:

Shaping positioning and framing so it reflects how developers actually evaluate tools
Validating that messaging aligns with development workflows, not idealized ones
Surfacing mismatches early, before they ship and become someone else’s problem
Representing developer reality consistently across product, sales, and marketing

This isn’t a checklist of tactics. When no one owns it, the gaps show up fast. Demos that fall apart under usage. Content that explains features but avoids constraints. Messaging that sounds right until someone tries to build with the product.

How developer marketing runs alongside other marketing functions

Developer marketing doesn’t replace product or growth marketing. In smaller companies, it often is product and growth marketing because one person owns the work end to end. As teams grow, the functions split out, but the responsibility doesn’t disappear.

In larger orgs, developer marketing becomes a coordinating role. Product marketing, growth, content, lifecycle, and RevOps have clear owners, but someone still has to keep the work aligned. Positioning has to match how the product actually works. Campaigns can’t get ahead of reality. Growth tactics can’t create downstream cleanup. That’s also why developer marketing experience scales into leadership. You’ve already had to own the whole system.

Developer marketing vs Developer Relations

Developer marketing and DevRel are often confused because they work with the same audience. They solve different problems. DevRel focuses on relationships, education, and feedback loops. Developer marketing focuses on clarity, positioning, adoption and revenue. There’s overlap in execution, but not in responsibility. They work best together. Things break when one is asked to replace the other.

Developer marketing in the AI era

The core responsibility hasn't changed. You still own trust, positioning, and credibility with a technical audience. But who that audience is and how they evaluate shifted. AI coding agents moved the constraint from writing code to describing what you want built. The people evaluating your product now include PMs, designers, and domain experts who build through prompts, not syntax. Developer content has two audiences now, humans and the AI agents helping them build. If your docs can't be parsed by an agent in Cursor or Claude Code, developers won't see your product at all.

I wrote more about this shift in End of coding, age of building.

How I think about being a better developer marketer

First, you should use the product. You should build with the thing you’re marketing. You should hit the same rough edges users hit and understand why they exist. It’s hard to explain limitations honestly if you’ve never run into them yourself.

Second, use AI aggressively, but deliberately. Automate repetitive work and invest in reusable tools, like a writing style guide or a Claude skill, so you’re not starting from scratch every time.

If you’re vibe coding, write instructions that explain what the generated code is doing. You should understand the structure of a codebase well enough to know where files live and how to update them manually if something breaks. Even if you work primarily in visual tools or AI editors, that baseline matters.

Build a sandbox. Have a place where you can play around with different dev tools and see how they actually behave. My site became my personal playground.

Learn from people who are close to the work and opinionated about it. I read an interesting question posed to potential hiring candidates, who do you think is doing marketing well? It made me run through the exercise and I think it’s important to follow folks who show their thinking, not just outcomes. Here are a couple folks that keep my wheels spinning, it a good way of course.

Hank Taylor - Developer Marketing Advisor, CodetoMarket
Morgane Palomares - VP of Marketing, Braintrust
Randall Degges - VP of AI Eng & DevRel, Snyk
Steve Sewell - CEO, Builder.io
James Hawkins - Co-CEO, PostHog

I keep most of this thinking written down so I don’t have to relearn the same lessons every time. I collect articles, threads, talks, and tools as gems. Over time, that gets distilled into my developer marketing handbook, which is where I capture how I approach personas, messaging, enablement, and GTM strategies when developers are part of the equation.

A note on how I actually apply this

I keep running into the same questions when I’m doing developer marketing work. What actually matters here? What’s noise? Where am I about to overcomplicate something or gloss over a constraint that will come back later?

One example is a Developer Marketing Claude skill I built that turns my developer marketing handbook into an interactive reference. I plan to use it to get oriented quickly and sanity-check decisions when I’m moving fast. It’s not meant to replace judgment or thinking. It’s there to reduce the cost of starting from scratch every time.

I’ve also published a developer marketing cheat sheet that pulls together roles and responsibilities, along with distribution channels and metrics. It’s intentionally lightweight and doesn’t require an email to download. If it’s useful, take it. If it’s not, ignore it.

What the job actually demands now

Doing this work well today requires more than knowing channels or tactics. It requires technical literacy, comfort operating between teams with unclear responsibility, and a willingness to be specific even when that means accepting tradeoffs. Most of all, it requires accountability for trust and revenue, not just reach.

What gets lost during leadership transitions

Fri, 09 Jan 2026 00:00:00 GMT

Over the past few years, I’ve seen the same pattern repeat across different companies, teams, and stages. It stopped feeling situational and started feeling structural. Leadership changes. Direction shifts. Teams reset. Then the same sequence plays out again.

I don’t think this usually comes from bad intent. Leadership choices shape the outcome in systems that reward visible change over durability. Over time, I started thinking about it as a flywheel. Not a formal model, just a way to explain why the same behaviors reinforce each other and keep repeating.

A pattern I keep seeing

It usually starts the same way. A new leader joins with a mandate to fix things. Expectations are high, time is limited, and the organization wants to see movement quickly. There’s pressure to create clarity and confidence, both internally and externally.

That pressure shapes the first decisions. Change becomes the most visible signal of ownership. Direction gets reset, priorities get reshuffled, and the org starts moving before there’s full context on why things look the way they do.

What follows is consistent enough that it’s hard to ignore:

A rebrand or reset of priorities
A restructure to match the new direction
People exit, sometimes by choice, sometimes not
New roles open that look a lot like the ones that were removed

Within a year to eighteen months, leadership changes again. The next person inherits a partially reset system, and the cycle starts over.

The leadership flywheel, as I see it

I think of this as a leadership flywheel because each step reinforces the next. New leadership enters under pressure to show progress. Visible change signals momentum. Structural and team changes follow. Outcomes take time. Leadership tenure runs out before those outcomes fully materialize.

The flywheel keeps moving not because anyone wants disruption, but because motion is easier to measure than durability. The system rewards visible change more than sustained execution.

Why leadership transitions often start with change

From the outside, change reads as action. From the inside, it often reads as necessity. New leaders inherit teams they didn’t build and strategies they didn’t choose. There’s limited trust in inherited context and little patience for slow understanding.

Resetting direction, structure, or messaging establishes ownership and creates distance from what came before. The issue isn’t that change happens. It’s that change becomes the starting point instead of the result of learning.

What gets lost first

The earliest losses are quiet. Context disappears. The reasoning behind past decisions fades. Work that was in motion loses sponsorship and stalls, not because it failed, but because no one is left to carry it forward.

Each transition removes another layer of institutional memory. Over time, teams stop assuming their work will compound. They expect it to be revisited.

What gets lost over time

As these transitions stack, the cost becomes harder to ignore. Strategy turns into something that’s constantly reworked instead of built toward. Teams get cautious about long-term bets. Confidence in direction erodes, even when the direction itself is sound.

People adapt by narrowing scope and shortening time horizons. Not because they lack ambition, but because they’ve learned what survives resets and what doesn’t.

The professional impact no one plans for

Leadership transitions don’t just reset strategy. They reset careers. Performance gets evaluated by managers who weren’t there for the work. Progress has to be re-explained. Advocacy disappears when leaders leave, often through no fault of the people they supported.

Growth becomes uneven. Not tied to output or impact, but to timing. This is one of the harder realities to talk about without sounding bitter, but it shapes how people experience their careers more than most organizations acknowledge.

I’ve experienced this firsthand, including situations where positive reviews, bonuses, and pay adjustments existed right up until a leadership change reset the narrative. In those moments, the work didn’t suddenly stop delivering. What changed was how success was defined and which outcomes mattered.

A leadership assumption worth challenging

Teams often get labeled as underperforming when the real issue is instability. Work doesn’t fail because the people were wrong for the role. It fails because the system never gave it time to land.

Strategy gets blamed when continuity was the missing ingredient. Changing players is easier than stabilizing the field, but it rarely addresses the underlying problem.

Entering a team without restarting the cycle

There’s another way to enter an organization, though it’s slower and less visible. Spend time with the team before reshaping it. Separate inherited issues from structural ones. Learn what’s already been tried and why it stalled.

Most teams don’t need to be replaced. They need space to operate without being reset every year. This doesn’t mean avoiding change. It means earning it.

Living inside leadership transitions

For people inside the system, there’s no clean answer. Some leave early. Some stay and adapt. Some get reshaped into roles they didn’t come in to do. Occasionally, a leader arrives who builds with what’s there instead of tearing it down, but you can’t plan on that.

What you can plan for is the reset.

You shouldn’t assume your previous performance reviews will be read. You shouldn’t assume context will carry forward. You shouldn’t assume the work you did speaks for itself once the people who sponsored it are gone. That’s frustrating, and it’s draining, but it’s also the reality of how often leadership changes.

Writing things down helps more than people want to admit. Not as self-promotion, but as continuity. Capture what you worked on, why it mattered, what changed because of it, and what didn’t get finished. Keep a record of decisions, outcomes, and tradeoffs while the context is still fresh.

This isn’t about selling yourself constantly. It’s about not starting from zero every time the org resets.

Over time, these notes become your own internal handoff doc. They make transitions survivable. They give you a way to ground conversations when direction shifts again. They help you advocate for your work without relying on memory or missing context.

You can’t stop the leadership flywheel alone, but you can make sure it doesn’t erase your contribution every time it turns.

Can a modern website run on Markdown + AI alone?

Mon, 15 Dec 2025 00:00:00 GMT

A debate surfaced over the weekend about whether teams still need a CMS at all. The idea is simple. If AI can draft content, migrate files, clean up structure, and commit everything to your repo, maybe you don’t need a content system. Everything becomes Markdown. Everything lives in Git. AI handles the busywork.

It’s a compelling argument for code-first teams.

But the real question is bigger.

Can an entire production website be built and maintained this way, or are there parts of a CMS that AI and Markdown still can’t replace?

And once you widen the scope to the whole website, a third option starts to matter too: visual development.

Here’s how these models actually compare.

The argument for Markdown and AI

Markdown has always been appealing to developers. It’s simple, local, versioned, and transparent. With AI acting on files the same way developers already do, a lot of friction disappears. You can:

draft content in your editor
use agents to clean up structure
generate frontmatter
fix formatting
reorganize folders
handle bulk changes
commit and deploy without leaving your flow

For a fully technical team, this model feels clean. There are no CMS dashboards to maintain, no API layers to wire up, and no separate content environments to manage. Everything lives in one place, and automation handles the repetitive work. It’s a real advantage for teams that operate entirely in code. But it also assumes something important: every contributor works like a developer. And most websites aren’t run that way.

Where Markdown starts to fall short

Markdown works well when content is simple and the team is small. That’s why some engineering-led teams can run it without friction. But once a website becomes a system instead of a collection of documents, Markdown introduces gaps that aren’t obvious until you hit them.

Some websites genuinely don’t need structured content, workflows, localization, or a cross-functional editing model. If your site is simple and your team is entirely technical, Markdown can work fine. But if your website relies on these capabilities, getting them in a Markdown workflow means building and maintaining them yourself.

Here are the big ones.

1. No structured content model

Some sites don’t need schema-level modeling. Many do. Production sites often rely on:

fields
types
relationships
reusable fragments
shared data across many surfaces

Markdown doesn’t enforce any of this. One missing field can break pages. One inconsistent value can break queries.

You can bolt on schema validation, but at that point you’re recreating parts of a CMS.

2. No safe editing environment

Markdown works for engineers. It doesn’t work for non-technical contributors. Even if AI generates the files, someone still ends up reviewing diffs or dealing with frontmatter.

Supporting broader teams means building:

internal UIs
guardrails around edits
validation layers

Otherwise, you're asking non-technical contributors to operate in Git.

3. No preview tied to actual components

Some engineering teams already maintain strong preview systems. Most don’t.

Without one, a Markdown file can’t show:

how a component renders
how content interacts with layout
how changes ripple across a page

You only see the real outcome after a build or preview deployment.

4. No built-in workflows

Websites need:

approvals
version history
scheduling
role-based access
localization
multi-surface consistency

Markdown doesn’t support this. Reproducing it means building bots, branch rules, and CI automation to simulate editorial workflows.

5. No shared space for collaboration

Markdown keeps contributors split across tools:

developers in Git
designers in Figma
marketers in docs
reviewers in comments elsewhere

There is no shared environment for the website itself. Markdown is simple until the website isn’t.

Can AI agents solve this gap?

AI agents can automate a lot inside a Markdown workflow. They can generate files, rewrite content, reorganize structure, migrate documents, clean up frontmatter, and handle several repetitive tasks developers used to own.

But agents don’t replace the systems that keep a full website consistent and safe.

To match what a CMS provides, AI agents would need to handle:

schema enforcement
field validation
relationship modeling
reference checks
localization parity
role-based permissions
publishing controls
approvals and sequencing
preview environments
multi-surface consistency

AI can help with pieces of this, but it can’t be the system.

To get all of these capabilities in a Markdown world, you’d need to build:

your own schema engine
your own validation pipeline
your own preview pipeline
your own workflow and approval model
your own contributor UI
your own localization framework
your own content governance rules
your own automation to prevent destructive edits

At that point, you’re not “avoiding a CMS.” You’ve built one. AI assists the work. It does not replace the infrastructure that coordinates it. This is the distinction most people miss.

The argument for a CMS

A CMS solves the problems Markdown can’t. It gives you structure, validation, workflows, and a safer way for non-technical contributors to manage content without touching code.

People don’t write inside the CMS. They publish inside the CMS.

That’s the important distinction.

Even if AI drafts and rewrites content, the CMS provides:

a consistent schema
a place to enforce rules
a predictable workflow
a safe environment to update live content
a shared model for content relationships
clear separation between editing and code

That’s why CMSs exist.

Not because writing is hard, but because maintaining content across teams requires structure that Markdown doesn’t provide on its own.

But CMSs are not perfect either. They can feel disconnected from the real site. They often separate content from layout. Editors can break things. API layers add overhead. Preview systems vary in quality.

So even though a CMS solves real coordination problems, it introduces friction in other areas.

This is why a third model matters.

The case for visual development

Visual development sits between Markdown and a CMS. It treats the website as a full system, not just content or code. It gives teams a shared environment with structure built in.

In a visual development model:

developers define components, logic, and structure
designers work directly in the real layout
editors update content inside the same system
schema and relationships stay consistent
content and layout stay aligned
AI operates with awareness of the actual components and fields

It removes the separation between:

content and layout
authors and developers
code and preview
structure and design

Markdown doesn’t provide this.

Headless CMSs rarely provide this.

And the role of AI changes completely in a visual development system. AI isn’t generating files in a vacuum. It works inside the actual structure of the site. That means:

AI site builders generate real pages using real components
AI visual editing adjusts layout, spacing, and structure with context
AI app scaffolding uses actual data models and extension points

AI doesn’t sit on the side. It participates in the system.

Visual development builds the website as one environment instead of splitting it across tools.

This is the gap Webflow fills.

ℹ️ Some platforms even combine visual development with Git-based workflows, like Builder.io's Fusion approach, which shows there’s real demand for visual editing that still fits into an engineering-centric versioning model.

So what does a team lose moving from a CMS to Markdown?

You lose:

schema enforcement
relationship modeling
predictable workflows
safe editing environments
shared context across teams
reliable previews (unless you maintain your own preview system)
localization pipelines
role-based permissions
structured publishing
cross-page consistency

You can rebuild some of this, but now you’re maintaining a custom system that grows in complexity as your website grows.

What a team gains by going Markdown-first

You gain:

full developer control
simpler architecture
fewer systems
automation through agents
transparency through Git
lower overhead

It’s a strong option for small, fully technical teams with simple content needs and tight ownership over the site.

It’s not designed for companies with cross-functional contributors or evolving structure.

What visual development offers instead

Visual development isn’t trying to be Markdown. It isn’t trying to be a CMS either.

It offers:

structure like a CMS
flexibility like a codebase
real layout context like a design tool
shared collaboration across roles
AI that works inside the true structure
developer extension points when needed

It’s the only model where the website stays a single source of truth for everyone.

Developers keep control. Designers keep fidelity. Marketers keep clarity. AI doesn’t act blindly. That’s why visual development matters in this debate.

The simple way to think about it

Markdown + AI

Great when the team is fully technical and the site structure is simple.

CMS

Great when content structure, governance, and shared responsibility matter.

Visual development

Great when a website is treated as a unified system where design, content, development, and AI all work together with real context.

Inside my developer marketing stack

Mon, 24 Nov 2025 00:00:00 GMT

Every builder has a rhythm to how they build. For me, that rhythm lives somewhere between code and content, the overlap where developer marketing happens. These tools help me stay organized, move faster, and keep projects on track without overcomplicating the work.

IDE

Cursor is now my main workspace after years in VS Code. They share the same foundation and extensions, but Cursor feels like where things are moving.

Same integrations and ecosystem as VS Code
Familiar setup that just works
AI that’s advancing faster than VS Code, which is surprising since GitHub built Copilot first
I pair it with Claude Code in the terminal for context, explanations, and large-scale debugging when I need deeper insight

It’s less about what’s new and more about pace. Cursor feels like it’s evolving while VS Code feels like it’s coasting.

AI chat tools

ChatGPT is my go-to for projects, building custom GPTs, and setting up connectors or integrations. I also use it for content curation when I’m gathering examples or early research.

Gemini handles search and visual creation. Its new Nano Banana feature makes generating visual references surprisingly quick.

Right now, both tools serve different purposes, but my guess is Gemini eventually edges out OpenAI. We’ll see.

Design and visual thinking

Figma is where I build and prototype designs. I don’t use its AI features, they’re still behind the curve. What makes it useful is how quickly I can move from layout ideas to something ready for production. Components, variables, and shared libraries keep everything consistent without extra effort.

Excalidraw is where I whiteboard. I sketch flows, map systems, and rough out diagrams before anything formal. A cheat code I use is generating Mermaid diagrams in ChatGPT to get a starting point, then rebuilding them in Excalidraw to make them clearer and more visual.

Analytics stack

A big part of developer marketing is understanding how people use what you build. These tools help turn product usage into insight.

PostHog for web analytics, event tracking, and session replay
FullStory for journey mapping and deeper behavioral insights
Sigma for the full view, from lead tracking to closed-won pipeline reporting
Looker for clean visualization and quick summaries

There isn’t one analytics platform that does everything well. A mix is usually the reality, and this is the combination that works for me.

Marketing and SEO stack

This is the set of tools I rely on to manage search, automation, and content performance. Each one plays a different role, from tracking technical SEO to finding new opportunities and testing campaigns.

Ahrefs is my go-to for monitoring technical SEO, tracking backlinks, and doing competitive keyword research or content gap analysis
SurferSEO helps grade keyword-focused content and tighten on-page structure before publishing
Google Keyword Planner is great for generating new ideas based on topics or URLs and gives solid monthly search volume data
Google Ads still earns its place, paid search still works, especially in developer marketing where people search everything (even Bing)
AirOps is a newer tool I’ve been using for automation workflows, from competitive intel to content research, all built through AI
Buffer is my social tool of choice, mainly because its free tier goes further than most and supports multiple platforms without friction
Common Room helps track and understand community activity across social, forums, and other developer channels.

This stack helps me connect research, creation, and distribution. It’s about staying close to what works and improving a little with each iteration.

Sales and enablement stack

This is where product knowledge turns into enablement.

Gong for reviewing customer calls and spotting themes that shape positioning and messaging
WorkRamp for internal education and onboarding content, keeping sales and marketing aligned on what’s new
Figma Slides for building presentations with real design flexibility. It feels like designing, not fighting templates.
Arcade for creating interactive product demos that help explain features in context without heavy editing or production time

They keep information flowing and teams aligned on what actually matters, the customers using the product.

Collaboration stack

Collaboration works best when it’s async, not noisy.

Notion is where I write everything, content drafts, specs, notes, and ideas. It’s underrated for collaboration and perfect for pulling in code snippets or assets. People think they need Google Docs, but they’re wrong.
Airtable is a dream for anyone who loves spreadsheets. It’s flexible, visual, and great for tracking content and projects. I’ve been a fan since day one, even if not everyone adopts it.
Slack is the only real choice for team communication. I live and die by the save-for-later feature, and the new canvas tools are great for organizing thoughts. Don’t at me with Microsoft Teams.
Loom is the best way to explain anything on video. It’s perfect for walkthroughs, feedback, or education. The editing tools are ok, not Descript-level, but work well enough. The AI still has some catching up to do.

This stack makes it easy to share work, document ideas, and keep everyone aligned without the constant back-and-forth.

Developer and Data Stack

This is where projects take shape.

GitHub for version control and collaboration
Supabase for quick databases and APIs
Vercel or Netlify for deployments
Warp for a cleaner, more visual terminal

It’s a reliable setup that scales smoothly and keeps development fast without adding unnecessary infrastructure.

Closing Thoughts

These tools have stuck because they make the work smoother. They cover everything I need to build, write, and collaborate without slowing things down.

The stack will keep changing, but the goal won’t.