Mert

Most AI cold email tools generate the same patterns. The same subject line structures, the same casual tone, the same call-to-action placement. And guess what? Spam filters see it coming from a mile away.

I built 99 Agents (a tool that scores cold email sequences for deliverability), and I’ve seen this play out thousands of times: technically well-written emails landing in spam folders because they feel like they came from an AI.

Here’s what actually works.

1. Structural Randomization: Break the Pattern

AI emails follow predictable rhythms. They have consistent sentence lengths, predictable paragraphs, and templated flows. Spam filters use pattern matching—if your email structure matches what they’ve seen 10,000 times before, you’re flagged.

What to do: Vary sentence length deliberately. Write one word sentences. Then longer ones. Mix short paragraphs with walls of text. The goal isn’t readability—it’s authenticity. Real humans write messy. Embrace the mess.

2. Avoid AI-Pattern Triggers

Certain phrases are red flags. “Hope this email finds you well.” (instant spam score bump). “I’ve been following your work.” (unless you’re specific, it reads generic). Exclamation marks in clusters. Perfect grammar. No typos, ever.

What to do: Include a real observation about their work. Name a specific article, feature, or milestone. Make one small grammatical choice that feels intentional but imperfect—a dash where a comma should be, or starting a sentence with “And” or “But.” Real founders do this. Filters expect it.

3. Subject Line Randomization

The most engineered subject lines fail. “[Name], quick question” or “Following up: [Company]” are template classics that filters have seen millions of times.

What to do: Write subject lines that feel weird in the moment but authentic. Ask a genuine question that might have multiple answers. Reference something specific from their Twitter/work that made you curious. Vary the format—don’t always lead with their name.

4. Timing and Volume

Blasting 500 emails at once is a spam death sentence. Even if each individual email is solid, the volume pattern is a giveaway.

What to do: Stagger sends across days or weeks. Vary send times. Don’t send to an entire list on Tuesday morning—that’s a bot pattern. Mix in real replies to people who respond, breaking the automation signal.

5. Breaking Brevity Myths

The advice “keep it under 150 words” is wrong. A perfectly short email can be more suspicious than a longer one because it’s so clearly templated.

What to do: Write naturally. Sometimes that’s short. Sometimes it’s longer with a real story. The best cold emails I’ve seen are 200-400 words with a specific ask buried in the middle—not at the bottom, not in a P.S.

How I Score This Stuff

When I built the Sequence Health Score for 99 Agents, we looked at thousands of emails that actually got replies vs. ones that hit spam. The pattern was clear: the ones that worked didn’t look like they came from a “cold email tool.”

They had personality. They broke their own rules. They felt like one founder emailing another, not a sequence.

The score looks at:

• Structural variation (sentence length, paragraph rhythm)
• Pattern triggers (how many template phrases you’re using)
• Personalization depth (not just {first_name}, but real context)
• Send behavior (volume, timing, list freshness)

Most AI tools max out at 2-3 of these. The ones that work nail all of them.

The Real Secret

Spam filters aren’t stupid. They’re trained on millions of real vs. spam emails. They can spot AI-generated text because AI text is too consistent. It’s too polished. It makes too much sense.

The best cold emails make less sense on the surface—because they’re written by a real person who’s thinking about the recipient, not optimizing for a template.

If you’re sending cold emails and they’re landing in spam, it’s not because you’re too pushy or too casual. It’s probably because the structure screams “automated.”

Randomize it. Make it weird. Make it real. That’s what works.

Check out 99 Agents if you want to score your next sequence: https://nine9agents.polsia.app?utm_source=devto&utm_medium=article&utm_campaign=launch

We’ll tell you exactly where your email is vulnerable and what to fix. No magic bullet—just honest feedback on why it might be hitting spam, and what real founders are doing instead.

Image by Jakub Żerdzicki on Unsplash.

At most teams, image handling is where “automated posting” quietly becomes manual again.

The text pipeline works. The publishing APIs work. But images end up as an afterthought: no attribution, inconsistent style, weak relevance, or missing cover fields on one platform. This post documents the production workflow we now use to fix that.

The Goal

Publish the same article to Hashnode and Dev.to with:

• one aligned hero image
• explicit image attribution close to the image
• platform-native cover mapping
• deterministic quality checks before publish

The Image Pipeline We Implemented

1. Generate article draft and title.
2. Query Unsplash using article-aware keywords.
3. Select a landscape image with strong topical fit.
4. Capture attribution metadata:
   • photographer name
   • photographer profile URL
   • photo page URL
5. Register Unsplash download tracking for compliance.
6. Map the same chosen image URL to both platforms:
   • Hashnode coverImageURL
   • Dev.to main_image
7. Insert attribution line directly beneath the first in-body image.

Why This Works Better

This workflow removes ambiguity. Instead of “find an image later,” every publish run has required image fields and a go/no-go quality gate.

That gives us:

• visual consistency across platforms
• proper author attribution on every article
• better click-through appeal
• fewer manual fixes after publish

Practical Rules We Enforce

• No image, no publish (unless explicit override).
• Attribution is mandatory and near the image.
• One canonical hero image per article for cross-platform consistency.
• Image must be public and renderable before API publish.

Final Note

Automation is only “production-ready” when content quality, attribution, and compliance are embedded into the workflow, not bolted on afterward.

This post itself was published through that exact pipeline.

Connect With Me

Krishna Soni — Game Developer, Researcher, Author of The Power of Gaming

LinkedIn: Krishna Soni | Kri Zek

Web: krizek.tech | Altered Brilliance on Google Play

Socials: Happenstance | Instagram @krizekster | Instagram @krizek.tech | Instagram @krizekindia

Love Terraform but hate HCL? CDKTF lets you write Terraform configs in TypeScript, Python, Java, C#, or Go.

What is CDKTF?

CDK for Terraform (CDKTF) is an open-source project by HashiCorp that lets you define Terraform infrastructure using programming languages instead of HCL.

Quick Start

npm install -g cdktf-cli
cdktf init --template=typescript --providers=aws

Your First CDKTF Stack

import { Construct } from "constructs";
import { App, TerraformStack, TerraformOutput } from "cdktf";
import { AwsProvider } from "@cdktf/provider-aws/lib/provider";
import { S3Bucket } from "@cdktf/provider-aws/lib/s3-bucket";
import { Instance } from "@cdktf/provider-aws/lib/instance";

class MyStack extends TerraformStack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    new AwsProvider(this, "aws", { region: "us-east-1" });

    // S3 Bucket
    const bucket = new S3Bucket(this, "app-bucket", {
      bucket: "my-app-assets-2026",
      tags: { Environment: "production" },
    });

    // EC2 Instance
    const server = new Instance(this, "web-server", {
      ami: "ami-0c02fb55956c7d316",
      instanceType: "t3.micro",
      tags: { Name: "WebServer" },
    });

    new TerraformOutput(this, "bucket-name", { value: bucket.bucket });
    new TerraformOutput(this, "server-ip", { value: server.publicIp });
  }
}

const app = new App();
new MyStack(app, "my-infra");
app.synth();

cdktf deploy

Loops and Conditions (Why CDKTF Wins)

// Create 3 identical servers with a loop
const serverNames = ["web-1", "web-2", "web-3"];
serverNames.forEach(name => {
  new Instance(this, name, {
    ami: "ami-0c02fb55956c7d316",
    instanceType: "t3.micro",
    tags: { Name: name },
  });
});

// Conditional resources
if (isProduction) {
  new Instance(this, "monitoring", {
    instanceType: "t3.large",
    // ...
  });
}

In HCL you would need count, for_each, and conditional expressions. In CDKTF — just use TypeScript.

Reusable Constructs

class WebApp extends Construct {
  public readonly url: string;

  constructor(scope: Construct, id: string, props: { domain: string; size: string }) {
    super(scope, id);

    const bucket = new S3Bucket(this, "assets", {
      bucket: `${props.domain}-assets`,
    });

    const server = new Instance(this, "server", {
      instanceType: props.size,
      ami: "ami-0c02fb55956c7d316",
    });

    this.url = server.publicDns;
  }
}

// Use it
const app1 = new WebApp(this, "app1", { domain: "example.com", size: "t3.micro" });
const app2 = new WebApp(this, "app2", { domain: "staging.example.com", size: "t3.small" });

CDKTF vs Pulumi vs HCL Terraform

Key Advantage: Full Terraform Ecosystem

CDKTF generates standard Terraform JSON. This means every Terraform provider, every module, every backend — it all works. You get TypeScript DX with Terraform reliability.

Need managed infrastructure for data extraction? Check out my Apify actors — no infrastructure management needed. For custom solutions, email [email protected].

I created a new website: Free Access to the 8 Volumes on Typescript & AI Masterclass, no registration required. Choose Volume and chapter on the menu on the left. 160 Chapters and hundreds of quizzes at the end of chapters.

Bridging Local Intelligence with Structured Workflows

The integration of Ollama with LangChain.js represents a significant shift in how we build intelligent applications. It moves us away from relying solely on cloud-based LLM APIs and towards a modular, locally-hosted ecosystem. This approach empowers developers to create more private, performant, and deterministic AI solutions. This post will dive into the core concepts, analogies, and practical code examples to help you understand and implement this powerful combination.

Understanding the Core Concepts: Raw vs. Structured Models

At its heart, the difference lies in how we interact with the Large Language Model (LLM). Direct API integration with Ollama, while functional, is akin to using low-level sockets – sending raw strings and receiving raw strings. This lacks structure, type safety, and the ability to chain operations seamlessly.

LangChain.js acts as the “Express.js” or “Next.js” framework for LLMs, providing the necessary abstraction layer. It wraps raw model calls in standardized interfaces (LLM, Embeddings, Runnable), enabling the creation of deterministic pipelines instead of imperative scripts.

Specifically, we’ll focus on two key components:

• OllamaLLM (The Reasoner): Handles text generation, taking a prompt and returning a completion. Crucially, it’s a “Runnable” that can be composed into larger chains.
• OllamaEmbeddings (The Vectorizer): Transforms text into numerical vectors (embeddings) capturing semantic meaning, allowing for similarity comparisons.

The Web Development Analogy: A Full-Stack Application

Think of a LangChain.js application like a modern full-stack web app:

• Database vs. Embedding Model (OllamaEmbeddings): A database stores data, but raw data is often unstructured. We index it with search engines like Elasticsearch or vector databases like Pinecone for efficient searching. OllamaEmbeddings is the “build process” that generates these indexes (vectors) from your text, ensuring your data stays local.
• API Route vs. LLM (OllamaLLM): An API route receives requests, processes logic, and returns responses. OllamaLLM is the serverless function or API endpoint, accepting a prompt and generating a response, but within a structured, orchestratable framework.
• Orchestrator vs. Chain: Tools like Redux or server-side middleware manage data flow in complex web apps. A LangChain Chain is the middleware pipeline, connecting retrieval to generation: Retrieve -> Format Prompt -> Generate -> Parse Output.

Why Integrate Ollama with LangChain.js?

Instead of raw API calls, why wrap Ollama in LangChain.js? The benefits are significant:

• Latency: Cloud LLMs involve network requests. With OllamaLLM locally, inference happens on the same machine, drastically reducing response times.
• Privacy: Data never leaves your machine, crucial for handling sensitive information (PII).
• Structured Output: LangChain’s Output Parsers enforce type safety, preventing crashes from malformed LLM responses.

Diving into the Code: A Basic Example

Let’s build a semantic search engine for a product catalog using Ollama and LangChain.js.

Prerequisites:

1. Ollama installed and running locally.
2. nomic-embed-text model pulled: ollama pull nomic-embed-text.
3. Node.js environment with langchain and @langchain/community installed.

// src/ollama-langchain-basic.ts

import { OllamaEmbeddings } from "@langchain/community/embeddings/ollama";
import { Ollama } from "@langchain/community/llms/ollama";
import { MemoryVectorStore } from "langchain/vectorstores/memory";
import { Document } from "langchain/document";

const embeddings = new OllamaEmbeddings({
  model: "nomic-embed-text",
  baseUrl: "http://localhost:11434",
});

const llm = new Ollama({
  model: "llama3.1",
  baseUrl: "http://localhost:11434",
});

const documents: Document[] = [
  new Document({
    pageContent: "The QuickStart Pro running shoes feature advanced cushioning technology for long-distance runners.",
    metadata: { category: "Footwear", price: 120, id: "prod_001" },
  }),
  // ... more documents
];

async function searchProducts(query: string): Promise<Document[]> {
  const vectorStore = await MemoryVectorStore.fromDocuments(
    documents,
    embeddings
  );
  const searchResults = await vectorStore.similaritySearch(query, 2);
  return searchResults;
}

async function generateResponse(query: string, context: Document[]) {
  const contextText = context
    .map((doc) => `Product: ${doc.pageContent} (Price: $${doc.metadata.price})`)
    .join("n");

  const prompt = `
    User Question: ${query}

    Context Products:
    ${contextText}

    Based on the context above, recommend the best product for the user.
    Be concise and friendly.
  `;
  const response = await llm.invoke(prompt);
  return response;
}

async function main() {
  const userQuery = "I need shoes for running marathons";
  const relevantDocs = await searchProducts(userQuery);
  const aiResponse = await generateResponse(userQuery, relevantDocs);
  console.log("n=== FINAL RESULT ===");
  console.log("Recommended Product:", aiResponse);
}

main();

This example demonstrates the core workflow: embedding the query, performing a similarity search, and generating a response using the retrieved context.

Advanced Application: Semantic Search with pgvector and Ollama

For production environments, consider using pgvector with Supabase for scalable semantic search. This architecture combines the benefits of local LLM inference with a robust vector database. The code would involve:

1. Server Action: Receiving the user query.
2. Embedding Generation: Using OllamaEmbeddings to create a vector representation of the query.
3. pgvector Search: Querying the documents table in PostgreSQL using pgvector to find similar documents.
4. Context Injection: Passing the retrieved documents to OllamaLLM for a context-aware response.

Performance Optimization & Common Pitfalls

Integrating Ollama with LangChain.js requires attention to performance:

• Memory Management: Be mindful of the keep_alive parameter in Ollama to free up resources.
• Concurrency: Node.js is single-threaded. Offload heavy processing using RunnableLambda or asynchronous operations.
• Token Limits: Local models have smaller context windows. Use splitters and limit retrieved chunks.
• Ollama Timeouts: Increase timeouts for CPU-heavy models.
• JSON Parsing: Handle potential errors when parsing LLM output.

Conclusion: The Future of Local AI

By integrating Ollama with LangChain.js, you’re building a local, distributed system that offers privacy, performance, and control. This approach unlocks a new era of AI development, empowering you to create powerful applications entirely on your own infrastructure. Embrace the power of local inference and structured workflows to build the next generation of intelligent applications.

The concepts and code demonstrated here are drawn directly from the comprehensive roadmap laid out in the book The Edge of AI. Local LLMs (Ollama), Transformers.js, WebGPU, and Performance Optimization Amazon Link of the AI with JavaScript & TypeScript Series.
The ebook is also on Leanpub.com: https://leanpub.com/EdgeOfAIJavaScriptTypeScript.

👉 Free Access now to the TypeScript & AI Series on Programming Central, it includes 8 Volumes, 160 Chapters and hundreds of quizzes for every chapter.

Multi-tenancy is one of those decisions that looks simple on a whiteboard and complicated in production. Choosing the wrong isolation model at the start — or not consciously choosing at all — creates a class of problems that are genuinely hard to undo later. Here’s what you should know before you write the first migration.

The Three Isolation Models (and the Trade-offs Nobody Leads With)

Every multi-tenant SaaS sits somewhere on a spectrum between full isolation and full shared infrastructure. There are three canonical patterns:

1. Separate databases per tenant

Each tenant gets their own database instance. Full data isolation, no risk of cross-tenant data leakage, clean tenant offboarding, and trivial per-tenant backup and restore.

The trade-offs: provisioning time increases, connection pool management gets complicated fast, schema migrations need to run across N databases, and cost scales linearly with tenant count. This model makes sense when you have strong compliance requirements, enterprise clients who mandate data isolation, or when per-tenant customisation of the data model is a real product requirement.

2. Separate schemas, shared database

One database server, but each tenant gets their own schema. This is Postgres-native and is a reasonable middle ground: you get logical separation without the operational overhead of separate database instances.

The catch: connection pooling tools like PgBouncer work at the connection level, not the schema level. You’ll need to set the search_path correctly per request, and some ORMs handle this gracefully and some don’t. Schema migrations still need to be coordinated across all tenants.

3. Shared schema, shared database (row-level tenancy)

Every table has a tenant_id column. All tenants share the same tables. This is the cheapest to operate, the simplest to migrate, and the easiest to onboard new tenants into.

The risk is the one that bites teams most: if you forget to filter by tenant_id anywhere in your application, a tenant can see another tenant’s data. This is not a theoretical risk — it has caused real security incidents. The mitigation is row-level security (RLS) at the database layer.

Row-Level Security: Use It, Don’t Trust the Application Layer Alone

If you go with the shared schema approach, Postgres RLS is not optional — it’s the last line of defence.

-- Enable RLS on the projects table
ALTER TABLE projects ENABLE ROW LEVEL SECURITY;

-- Create a policy that restricts reads to the current tenant
CREATE POLICY tenant_isolation ON projects
  USING (tenant_id = current_setting('app.current_tenant_id')::uuid);

Then in your application, set the tenant context at the start of each request:

SET app.current_tenant_id = '{{tenant_uuid}}';

This means that even if your application code has a bug and omits the tenant_id WHERE clause, the database enforces the boundary. Defence in depth.

The cost: current_setting() calls add marginal overhead per query. In practice this is negligible for most workloads, but benchmark it if you’re operating at very high query rates.

The Tenant Resolution Problem

How does your application know which tenant a request belongs to? There are three common approaches, each with real implications for your routing and infrastructure:

Subdomain-based: acme.yourapp.com → resolve acme to a tenant.
Clean for end users. Requires wildcard TLS, and your CDN/load balancer needs to handle arbitrary subdomains. Custom domains (where a tenant uses app.acmecorp.com) add another layer of complexity: you need to map arbitrary domains to tenant IDs at the edge.

Path-based: yourapp.com/t/acme/dashboard
Simpler infrastructure. Less ergonomic for users. Works everywhere including native apps. Good for internal tooling or B2B products where users don’t care about the URL.

Token-based: tenant encoded in the JWT or session token.
Common for API-first products. Tenant context is explicit in every request. No DNS dependency. Slightly more complex auth middleware.

Most teams mix approaches: subdomain for the main app, token-based for the API.

Schema Migrations at Scale

This is the operational burden that takes teams by surprise. In a single-tenant app, a migration runs once. In a multi-tenant app with separate databases or schemas, it runs N times.

For shared-schema tenancy, this is not a problem — migrations run once. For schema-per-tenant or database-per-tenant, you need a migration runner that can:

1. Track migration state per tenant
2. Run migrations in parallel (with configurable concurrency)
3. Handle failures gracefully — partial rollouts should not leave some tenants on schema version 7 and others on version 8 invisibly

A pattern that works well: maintain a tenant_migrations table in your management database that records the current migration version for each tenant. Your deployment pipeline queries this table, identifies tenants not at the current version, and runs migrations in batches.

Tenant Onboarding: Provisioning New Tenants Efficiently

In a shared-schema model, onboarding a new tenant is simply inserting a row into a tenants table and using the generated ID as the tenant_id in all subsequent writes. It’s fast, it’s atomic, and it doesn’t require any infrastructure changes.

In a schema-per-tenant model, onboarding requires creating a new schema and running the baseline migrations against it. This adds latency to the signup flow — typically seconds for small schemas, potentially minutes for large ones. The standard approach is to provision the tenant schema asynchronously and show a “getting your workspace ready” state to the user while it completes.

In a database-per-tenant model, provisioning is the most expensive: create a new database instance, configure access, run migrations, and update the routing table. This is typically a background job that takes minutes, and the user experience must be designed to accommodate it.

Plan your onboarding UX around your provisioning model. Don’t discover the mismatch after you’ve shipped.

Don’t Confuse Multi-Tenancy with Multi-Instance

One thing worth saying explicitly: multi-tenancy is a data architecture and application design concern, not an infrastructure concern. You can run a multi-tenant application on a single server or across hundreds. You can run a single-tenant application in Kubernetes with 50 replicas.

The isolation model lives in your data layer and your application logic. Infrastructure decisions about scaling, availability, and deployment are separate — important, but separate.

For a deeper look at the specific patterns and when to apply each, the Actinode guide on multi-tenant SaaS architecture covers the full decision matrix including compliance considerations and per-pattern migration strategies.

Summary

The choice you make here will be with you for years. Make it deliberately.

A Note on Testing Your Isolation Model

Whatever model you choose, write explicit tests that verify your tenant isolation holds. Not just unit tests for the query logic — integration tests that simulate cross-tenant access attempts and verify they fail at the database layer.

A test suite that catches isolation failures looks like this:

1. Create two test tenants with separate datasets
2. Authenticate as tenant A
3. Attempt to read tenant B’s records via your application’s own API routes
4. Assert the response contains zero tenant B records

This test should run in your CI pipeline on every merge. Tenant isolation failures are the kind of bug that makes the news, and the cost of catching them in CI is trivially low compared to the cost of discovering them in production.

The same principle applies to your RLS policies: write a test that connects to Postgres with the RLS policy active, sets app.current_tenant_id to tenant A’s ID, and attempts to SELECT tenant B’s rows directly. If RLS is working correctly, the query returns zero rows. If it returns any rows, your policy has a gap.

Isolation is a correctness property, not just a design preference. Test it like one.

I used Anki for a long time.

It made sense back then. You had a word list,
you needed to memorize it, you drilled it
until it stuck. Simple. Effective enough.

But it’s 2026. And I think we need to have
an honest conversation about why Anki is
starting to feel like a fax machine in a
world of instant messaging.

The uncomfortable truth about flashcards

I was memorizing words. Not learning them.

There’s a difference — and it took me embarrassingly long to see it.

When you drill “ephemeral → short-lived” a hundred times, your brain stores a weak, isolated link. It knows the definition. It does not know the word.

But when you read “the beauty of cherry blossoms is ephemeral — they last only one week” — something different happens. Your brain attaches the word to a scene, an emotion, a moment. That’s the kind of memory that survives a real conversation.

This is called contextual encoding. It’s not a new idea — memory researchers have known this for decades. And yet almost every flashcard app ignores it completely.

I got frustrated enough to build
MindDory — an app
that uses AI to wrap your target vocabulary
in short contextual stories instead of
isolated cards.

So I built MindDory

The idea was simple: what if instead of isolated cards, an AI generated short stories around exactly the words you need to learn?

You read the story. The words appear in context. Your brain does what it’s actually designed to do.

I also added memory cues — smart keyword associations for the words that just refuse to stick — and spaced repetition to handle the review timing automatically.

Honestly? It felt like cheating compared to my old Anki routine.

Three things building this taught me

The hardest part had nothing to do with code.

I spent weeks just trying to understand why people fail at language learning. Reading research papers at midnight. Talking to strangers on Reddit about their Anki burnout. Watching where the drop-off happens.

The answer was always the same: isolation. Words learned without context don’t transfer to real life. Full stop.

My first version was too clever.

I stuffed it with features I thought were cool. Users opened the app, got confused, and left. So I stripped everything back to the core loop: encounter a word → see it in a story → review it later. That’s it. Everything else is noise.

Distribution is genuinely harder than building.

I’m a builder. I like building. But getting MindDory in front of people who actually need it? That’s a completely different skill set — and honestly the thing I’m still figuring out.

If you’ve shipped something and cracked distribution, I’d love to know how. Drop it in the comments. I mean it.

Where things stand

MindDory is live on the App Store. Free to try. English, French, Korean, Chinese and more.

If you’ve ever felt like Anki was grinding you down without actually making you fluent — that’s exactly who I built this for.

And if you have thoughts on contextual learning, memory science, or just want to tell me I’m wrong about something — please do. That’s the kind of conversation I’m here for.

If you’re curious what contextual learning
looks like in practice, I built MindDory
around this idea — minddory.com

Most startups don’t fail after launch — they fail because of decisions made before a single line of production code was written. After seeing the same patterns repeat across dozens of early-stage builds, I want to document five of the most common MVP development mistakes and what they actually cost you.

Mistake 1: Treating the MVP as a Smaller Version of the Full Product

This is the most expensive mindset error you can make.

An MVP is not a product with features removed. It is a hypothesis with a delivery mechanism. The question is not “what’s the minimum we can ship?” — it is “what is the fastest way to learn whether this problem is real and whether our solution addresses it?”

When teams approach an MVP as a stripped-down full product, they still make the same architectural decisions, the same data model choices, and the same tech stack trade-offs they’d make for a mature system. The result: a system that takes 6 months to build and 3 months to change after you learn you got the core assumption wrong.

The fix: Start with user stories, not feature lists. Every piece of the MVP should be traceable to a specific assumption you need to validate. If you can’t name the assumption a feature is testing, cut the feature.

Mistake 2: Optimising for Scale Before You Have Users

Premature scalability is the startup equivalent of building a 10-lane highway before anyone has applied for a driving licence.

Multi-region deployments, event-driven microservices, database sharding strategies — these decisions have real costs: complexity, slower development, harder debugging, and more expensive infrastructure. They make sense when you have the load to justify them. In an MVP, they are often just risk without corresponding reward.

The default starting point for most web applications — a single server, a relational database, a simple monolith — will comfortably handle the traffic of the vast majority of early-stage products. The systems that fail at early-stage aren’t failing because the architecture wasn’t distributed enough; they’re failing because the product wasn’t validated enough.

Scale for the users you have plus a reasonable buffer. Save the architecture work for when you actually have the problem.

Mistake 3: Skipping Auth and Permissions “Until Later”

Authentication and authorisation are never “later” problems. They’re day-one problems, and retrofitting them into an existing system is disproportionately expensive.

The reason this mistake happens is understandable. Auth feels like plumbing. You want to build features. And in the very earliest prototype — a Figma walkthrough, a Typeform, a manual demo — you don’t need auth at all. But once you have real users interacting with a real system, the risk of skipping this is not theoretical. You’re one shared session cookie away from a user seeing another user’s data.

Modern auth libraries (Clerk, Auth0, NextAuth, Supabase Auth) have dramatically reduced the cost of getting this right from the start. There is no good reason to skip it.

Mistake 4: Building Without a Feedback Loop Mechanism

An MVP without feedback infrastructure is just software. The whole point is to learn, and learning requires a structured way to capture what users do and what they say.

This doesn’t mean building a full analytics platform. It means, at minimum:

• Event tracking on the actions that matter (sign up, core feature use, upgrade, churn trigger)
• A way for users to tell you something is broken or confusing (even a Typeform link)
• Some form of session context so you can replay what happened before a support request

Many early teams ship without any of this, then try to diagnose growth problems by asking users in one-on-one calls. One-on-one calls are valuable, but they don’t scale and they’re subject to recall bias. Instrument your product from the start.

Mistake 5: Changing the Scope Mid-Build Without Updating the Timeline

Scope creep is normal. The decision to add a feature mid-sprint is sometimes the right one — you learn something that changes priorities. The problem is doing it without honest reckoning on what it costs.

Every new feature in an MVP build is not additive. It delays launch, adds surface area for bugs, and often introduces coupling that makes future changes harder. When scope changes happen without timeline adjustment, the team compensates by cutting quality: less testing, rushed implementation, deferred refactoring.

The discipline is simple but hard: when you add scope, remove an equivalent amount of scope or explicitly extend the timeline. Make the trade visible. Don’t absorb it invisibly into “we’ll just work harder.”

What an MVP Actually Needs to Succeed

Beyond avoiding these five mistakes, there are a few things that actively drive MVP success that don’t get talked about enough.

A clear definition of “validated.” Before building, write down the specific signal that would tell you the hypothesis is true. Not “people seem interested” — a concrete metric: 30 users completed the core flow, 10 paid, 5 renewed. Without a pre-defined threshold, confirmation bias fills the vacuum and teams convince themselves the signal is there when it isn’t.

Fast feedback cycles, not perfect execution. The goal of an MVP sprint is to reach a learning checkpoint as fast as possible. A good MVP process prioritises shippability and measurability over technical polish. You’re building the minimum surface area needed to generate a signal — then iterating based on what you learn, not on what you assumed.

Documented assumptions before you start. Write down what you believe to be true before you build. Not just the product assumptions — the market assumptions, the pricing assumptions, the onboarding assumptions. When you get data back, you’ll know what changed and what held. Teams that skip this step have no reliable way to learn from their own MVP results.

If you’re currently planning an MVP build, the roadmap matters as much as the stack. The Actinode guide on building from zero to your first 1,000 users walks through the phased approach in detail — what to build in each stage and what to deliberately leave out.

The common thread in all five mistakes above is the same: treating MVP development as a compression of product development, rather than a distinct discipline with its own goals and constraints. The two are not the same, and conflating them is expensive.

One More Thing: Define “Done” Before You Start

A final practical note that doesn’t fit neatly into any of the five mistakes but underpins all of them: define what “done” means for your MVP before you build it.

Not done as in “features shipped” — done as in “we’ve answered the question we set out to answer.” Write down the specific signal that would tell you your core hypothesis is true. A number of users, a conversion rate, a retention metric, a willingness-to-pay threshold. If you can’t write it down before you build, you won’t be able to read it accurately after you ship.

This definition protects you from two failure modes. The first is the MVP that ships but never generates a decision — you collect some signal, it’s ambiguous, and you keep iterating without ever committing to a direction. The second is the MVP that gets declared a success based on vanity metrics — pageviews, signups, demo requests — that feel like progress but don’t validate whether the core assumption holds.

Every good MVP has a clear question it’s trying to answer. That question should be written down before the first commit is made.

This is a submission for the Notion MCP Challenge

What I Built

I built a Governed MCP-Based AI Agent System where real-world actions are executed through tools — but always under strict policy control.

Instead of focusing only on what agents can do, this system enforces what they are allowed to do — and what must be blocked.

Core Idea

Use MCP as the capability layer and Actra as the governance layer:

• MCP exposes real tools (Notion workspace actions)
• The AI agent selects and invokes these tools
• Actra evaluates every tool call before execution

This creates a system where:

Capability is separated from control.

How It Works (in practice)

In the demo:

1. The agent connects to Notion via MCP
2. It discovers available tools:

   notion-search
   notion-get-users
   notion-create-pages

1. The agent attempts to execute actions

Step 1 — Uncontrolled Agent (Baseline)

No policy enforcement ❌
Agent executes tools freely

• search works
• user data can be accessed
• write operations are possible

The agent has full power — with no guardrails.

Step 2 — Actra-Governed Agent

Actra is introduced as an in-process policy engine.
Every tool call is evaluated before execution.

What Gets Enforced

1. Input validation

Empty search →  Blocked
Rule: block_empty_search

2. Context-based control

safe_mode = true → Block writes
Rule: block_writes_in_safe_mode

The agent still knows about the tool — but cannot execute it.

What Makes This Different

Most AI systems:

• rely on prompts or heuristics
• enforce rules inconsistently
• lack clear visibility into decisions

This system:

• enforces policies deterministically at runtime
• separates decision-making from control
• provides explicit reasoning for every block

What This Enables

• Safe AI agents for real-world workflows
• Controlled access to sensitive operations
• Clear auditability of decisions
• Policy-driven execution instead of implicit behavior

Core Insight

MCP gives agents capability.
Actra decides whether that capability can be used.

This transforms AI agents from:

“systems that can act”

into:

systems that can act — safely, predictably, and under control.

What Makes This Different

Instead of blindly executing AI actions, every decision is evaluated against policies like:

• ❌ Block sending sensitive data externally
• ❌ Restrict unsafe API calls
• ❌ Prevent unauthorized actions
• ✅ Allow only whitelisted operations

This turns Notion + AI from a productivity tool into a safe execution environment for real-world workflows.

Video Demo

Show us the code

https://github.com/getactra/notion-mcp-governed-agent

Repo Structure

.
├── LICENSE
│   └── Project license

├── auth
│   ├── callback.ts
│   │   └── Handles OAuth redirect/callback after user authentication
│   ├── exchange.ts
│   │   └── Exchanges authorization code for access/refresh tokens
│   ├── metadata.ts
│   │   └── Fetches auth provider metadata (endpoints, configs)
│   ├── pkce.ts
│   │   └── Implements PKCE (Proof Key for Code Exchange) helpers
│   ├── register.ts
│   │   └── Actra MCP client registration with auth provider (client_id, etc.)
│   ├── state.ts
│   │   └── Save OAuth state
│   └── url.ts
│       └── Builds authorization URLs for login flow

├── mcp
│   └── client.ts
│       └── MCP (Model Context Protocol) client wrapper
│           handles communication with MCP server/service

├── package.json
│   └── Project dependencies, scripts, and metadata

├── test-step1.ts
│   └── Initial test/setup (MCP connection)

├── test-step2.ts
│   └── Next step test 

├── test-step3.ts
│   └── Intermediate flow test

├── test-step4.ts
│   └── Loads Notion MCP tools

├── test-step5-unsafe-agent.ts
│   └── Demonstrates an agent without safeguards
│       (To show risks accessing Notion without safeguards)

└── test-step6-actra-governed-agent.ts
    └── Agent with ACTRA governance layer
        (adds rules, constraints, or safety controls)```



### Example Policy



```yaml
version: 1

rules:
  # Block writes in safe mode
  - id: block_writes_in_safe_mode
    scope:
      action: notion-create-pages
    when:
      subject:
        domain: snapshot
        field: safe_mode
      operator: equals
      value:
        literal: true
    effect: block

  # Block empty search
  - id: block_empty_search
    scope:
      action: notion-search
    when:
      subject:
        domain: action
        field: query
      operator: equals
      value:
        literal: ""
    effect: block

How I Used Notion MCP

Notion MCP acts as the execution layer between an AI agent and real-world actions.

Instead of just reading data, the agent can:

• discover available tools
• execute operations (search, fetch, create, update)
• interact with a live Notion workspace

Role of MCP in this system

In my setup, MCP is responsible for:

• Tool discovery

  notion-search
  notion-get-users
  notion-create-pages

• Tool execution

  client.callTool({ name, arguments })

• Standardizing agent capabilities
  → every action becomes a structured tool call

What This Enables (and Why It’s Risky)

With MCP alone:

• the agent can read workspace data
• the agent can modify content
• the agent can access users and metadata

In Step 5 (uncontrolled agent):

No policy enforcement ❌
Agent executes tools freely

This means:

The agent has full capability, but no control

Adding Actra (What Changes)

With Actra layered on top:

• every tool call becomes a policy-evaluated action
• execution is conditionally allowed or blocked
• decisions are deterministic and explainable

In Step 6 (governed agent):

❌ Blocked by Actra
Rule: block_get_users

The agent still has capability — but no longer has unrestricted power

What This Unlocks

Without MCP:

• Notion is just a UI or database

With MCP:

• Notion becomes a programmable execution surface

With MCP + Actra:

• It becomes a governed AI system

• Actions are:

  • validated
  • controlled
  • auditable

Architecture

Notion (Workspace / Tools)
        ↓
     MCP Layer
   (Tool Discovery + Execution)
        ↓
     AI Agent
        ↓
   Actra Runtime
 (Policy Evaluation Engine)
        ↓
 Allowed / Blocked 
        ↓
   Tool Execution (or Denied)

Key Insight

MCP gives agents power.
Actra decides how that power is used.

Why This Matters

As AI agents become more powerful, governance becomes critical.

This project shows that:

• you don’t need heavy infra
• you don’t need external policy services

You can enforce deterministic, auditable control directly inside your application.

Future Work

• Role-based policies (team / org level)
• Policy simulation + testing UI inside Notion
• Full MCP-native agent orchestration
• Audit logs and explainability dashboards

Closing Thought

Everyone is building AI agents.

Very few are thinking about control, safety, and governance.

This project is a step toward making AI systems not just powerful — but trustworthy.

Developers using AI coding tools believe they’re 24% faster. Measured objectively, they’re actually 19% slower. That’s a 43-point perception gap, and it explains a lot about why AI tool adoption keeps rising while trust keeps falling.

The data comes from the METR study, which measured experienced open-source developers working on their own repositories with tasks they selected themselves. This wasn’t a lab experiment with toy problems. These were real developers doing real work, and the AI made them measurably less productive while making them feel more productive.

Here’s what’s actually happening, and why it matters for how you use these tools.

The perception gap is the finding

The headline “AI makes you slower” is catchy but misses the point. The real finding is that developers can’t tell whether AI is helping them or not.

The study found that developers consistently overestimated the time savings from AI assistance. They reported feeling faster, more confident, and more productive. The clock said otherwise. The gap came from time spent on activities that feel productive but aren’t: reviewing AI suggestions, debugging AI-generated code, re-prompting after bad outputs, and context-switching between their own thinking and the AI’s suggestions.

This matches what the Stack Overflow 2025 Developer Survey found at scale: trust in AI accuracy dropped to 29%, down from 40% the year before. 46% of developers actively distrust AI tool accuracy. Developers are using the tools more while trusting them less, which is a strange place to be.

Where AI actually helps (and where it doesn’t)

The METR study doesn’t say AI is useless. It says AI on familiar codebases with experienced developers doesn’t save time on average. That’s a specific finding about a specific context.

Other data tells a more nuanced story. The CodeRabbit analysis of 470 GitHub repositories found AI-authored code has 1.7x more issues than human-written code. But the distribution matters:

The pattern: AI excels at tasks where broad training data matters more than local project context. It struggles where deep understanding of a specific codebase is required. Refactoring your own code on a project you know well is the worst case for AI assistance because you already have the context the AI lacks.

Why experienced developers get less benefit

This is counterintuitive. You’d expect experienced developers to get more from AI tools because they can better evaluate and direct the output. Google Chrome engineering lead Addy Osmani made this argument and it’s partly right: experts do use AI more effectively than beginners.

But the METR study suggests a ceiling effect. When you already know a codebase well, the AI’s contribution is marginal. You can write the code yourself about as fast as you can prompt, review, then correct the AI’s attempt. The overhead of the human-AI collaboration loop (prompt, wait, read, evaluate, accept/reject, fix) eats the time savings from not typing the code yourself.

For beginners or developers working on unfamiliar codebases, the calculus is different. The AI brings knowledge the developer doesn’t have. But the GDC 2026 report found that among game developers who use AI, 81% use it for research and brainstorming, 47% for code assistance, and only 35% for prototyping. Most developers have already figured out that AI works better for exploration than execution.

What to actually do with this information

The METR study doesn’t mean you should stop using AI tools. It means you should be more intentional about when you use them.

Use AI for code you don’t know. Exploring a new library, understanding an unfamiliar codebase, generating boilerplate for a framework you’ve used twice. These are contexts where the AI’s broad training data genuinely helps.

Don’t use AI for code you know well. If you’ve written similar code 50 times, your fingers are faster than the prompt-review-fix loop. The METR study specifically found that experienced developers on familiar repositories were the ones who got slower.

Watch for the perception trap. If you feel like AI is making you faster, check the data. Track how long tasks actually take with and without AI. The 43-point perception gap means your intuition about AI productivity is probably wrong.

Treat AI output like a junior developer’s PR. Review it with the same scrutiny. The CodeRabbit data shows AI code has 1.75x more logic errors and 8x more excessive I/O operations. A quick skim is not sufficient review.

Use AI for understanding, not generation. “Explain this function” and “What does this error mean” are consistently the highest-value AI use cases across every study and survey. The generation use case gets all the marketing attention, but the comprehension use case delivers more actual value.

The productivity question is the wrong question

The deeper issue with the METR study is that “does AI make developers faster?” might be the wrong question. Speed is one metric. Code quality, security, maintainability, developer satisfaction are others.

The Cortex 2026 Engineering Benchmark found incidents per pull request increased 23.5% and change failure rates rose ~30% across engineering teams adopting AI tools. Developers are shipping more code, but the code is causing more problems.

If AI makes you feel 24% faster while actually making you 19% slower and producing 1.7x more bugs, the net effect on your project is significantly negative. The teams that figure this out and use AI selectively (for comprehension and exploration) rather than universally (for all code generation) will outperform those that don’t.

The tools will get better. The models will improve. But the perception gap will persist as long as developers rely on how AI-assisted coding feels rather than measuring what it produces.