Every AI model hits the exact same wall: context window limits. A few million tokens sounds huge on paper. Until you actually start building real software with an AI agent.

Here's the catch that catches most developers off guard: LLMs have zero long-term memory.

Every single prompt in a chat session starts from scratch. The model doesn't "remember" what you worked on ten minutes ago. To maintain continuity, your coding assistant has to re-read the entire conversation history on every single request — every prompt, every snippet, every terminal log, from line one.

In a casual Q&A chat, you barely notice. In active software development, it's a disaster. Along with your instructions, the agent receives massive code dumps: entire files, multi-line diffs, terminal outputs, linter errors, and test suite logs.

Context snowballs fast. The larger the context payload, the more money you burn per query — and the less room remains for actual code generation.

Eventually, the teams building AI coding tools landed on two common-sense principles:

1. Keep context tight — Feed the model only what it strictly needs. Trim the noise, shorten the prompt payload, and cut down unnecessary reasoning cycles.
2. Give the agent a cheat sheet — A concise, structured file detailing your project's rules, stack, and boundaries. That way, the agent doesn't waste thousands of expensive tokens trying to "figure out" whether you use pnpm or npm, or which directories it's forbidden to touch.

Without this cheat sheet, AI agents are essentially coding blind. They don't know your team banned yarn. They don't know that src/generated/ is a CI-built sacred cow that must never be hand-edited. They don't know your API handlers return Result<T, E> instead of throwing exceptions. They're brilliant generalists, but completely clueless about your repository's unwritten rules.

That's why AGENTS.md exists — a lightweight Markdown file that hands AI agents the rules of the game for your codebase. It takes up negligible token space while giving the model maximum guidance.

---

The Backstory: Tearing Down the Vendor Tower of Babel

Before AGENTS.md, every AI tool vendor invented its own isolated solution to the context problem. Cursor gave us .cursorrules. Anthropic pushed CLAUDE.md. GitHub built .github/copilot-instructions.md. Windsurf introduced .windsurfrules.

By 2025, a standard project root looked completely absurd:

textCopy
1my-project/
2├── .cursorrules              # Rules for Cursor
3├── CLAUDE.md                 # Rules for Claude Code
4├── .github/
5│   └── copilot-instructions.md   # Rules for GitHub Copilot
6├── .windsurfrules            # Rules for Windsurf
7├── .continue/
8│   └── config.json           # Rules for Continue
9└── README.md                 # ...and an actual README for humans!

You ended up with five near-identical files that drifted out of sync within a week. You'd update a linting rule in .cursorrules, forget to touch CLAUDE.md, and suddenly Claude Code is generating outdated boilerplate. Classic version drift — except instead of code and tests diverging, your instructions for different AI tools were fighting each other.

It's like writing five separate onboarding guides for five new hires and giving each person slightly different rules. Chaos is guaranteed.

To kill off this fragmentation, major tech players rallied around an open, vendor-agnostic standard: AGENTS.md. Today, it's governed by the Agentic AI Foundation (AAIF) under the Linux Foundation, backed by AWS, Anthropic, Google, Microsoft, OpenAI, Block, and others.

---

What is AGENTS.md? Human README vs. Machine README

The core idea is dead simple. Every serious project has a README.md explaining to humans what the project does, how to set it up, and how to contribute. AGENTS.md is the exact same concept, built specifically for AI agents.

mermaidCopy
1flowchart TD
2    Repo["Code Repository"]
3    Repo --> README["README.md<br/>(For Humans)"]
4    Repo --> AGENTS["AGENTS.md<br/>(For AI Agents)"]
5
6    README --> R1["Why does this project exist?"]
7    README --> R2["How to install and run it?"]
8    README --> R3["Who wrote this and under what license?"]
9
10    AGENTS --> A1["Which files are strictly off-limits?"]
11    AGENTS --> A2["What exact CLI commands build & test this?"]
12    AGENTS --> A3["What coding patterns must be followed?"]

Different audiences require fundamentally different writing styles:

	README.md	AGENTS.md
Reader	Human Developer	AI Agent (LLM)
Tone	Welcoming, descriptive	Imperative, strict
Goal	Explain, inspire, onboard	Direct, enforce, prevent mistakes
Example	"We use React 19 and TanStack Router for routing"	"ALWAYS use pnpm. NEVER run npm or yarn"
Optimization	Visual layout & scannability	Token efficiency & prompt budget

Pay close attention to tone. A human README uses polite, welcoming language ("We prefer..."). AGENTS.md uses hard imperatives ("ALWAYS...", "NEVER..."). Your AI agent isn't a colleague whose feelings you might hurt. It's a high-speed execution engine that needs direct orders, not diplomatic suggestions.

---

Ecosystem Support: Who Reads AGENTS.md?

The short answer: almost every major coding tool on the market. Today, native support for AGENTS.md includes:

mermaidCopy
1flowchart LR
2    subgraph Spec["Single Source of Truth"]
3        AGMD["📄 AGENTS.md"]
4    end
5
6    subgraph Agents["AI Agents and IDEs"]
7        Cursor["Cursor"]
8        OpenAI["Codex"]
9        Copilot["GitHub Copilot"]
10        ClaudeCode["Claude Code"]
11        Aider["Aider"]
12        OpenHands["OpenHands"]
13        Windsurf["Windsurf / Devin"]
14        GeminiCLI["Gemini CLI / Antigravity"]
15        Goose["Goose"]
16    end
17
18    AGMD ==> Cursor
19    AGMD ==> OpenAI
20    AGMD ==> Copilot
21    AGMD ==> ClaudeCode
22    AGMD ==> Aider
23    AGMD ==> OpenHands
24    AGMD ==> Windsurf
25    AGMD ==> GeminiCLI
26    AGMD ==> Goose

• OpenAI Codex — automatically picks up AGENTS.md at session boot. Supports nested directory rules and global ~/.codex/AGENTS.md fallbacks for personal defaults across all repos.
• Cursor — parses AGENTS.md across project folders and injects relevant rules into prompt context (alongside .cursor/rules/*.mdc).
• GitHub Copilot Coding Agent — uses AGENTS.md as its primary project rules source.
• Claude Code — parses both AGENTS.md and CLAUDE.md, automatically giving precedence to AGENTS.md when both are present.
• Aider — loads AGENTS.md as project conventions on launch.
• OpenHands / SWE-bench agents — scan AGENTS.md to bootstrap baseline environment context.
• Gemini CLI / Antigravity — natively consumes AGENTS.md for project scoping.
• Goose (Block) — treats AGENTS.md as a core specification.
• Zed / JetBrains Junie / VS Code / Warp / Devin / Windsurf / Amp / RooCode — plus dozens of emerging tools.

One file, zero duplicate configs.

💡 Pro-tip for legacy tooling: If you're stuck on an older tool version expecting vendor-specific filenames, just symlink them:

bashCopy
1ln -s AGENTS.md CLAUDE.md
2ln -s AGENTS.md .cursorrules

One source of truth, zero maintenance overhead.

---

Monorepos: The "Closest File Wins" Rule

In a large monorepo, a single root-level AGENTS.md rarely cuts it. Your frontend team is running React with Vitest; your backend team is on Go with golangci-lint; your data team is writing Python with pytest. They use different test commands, different linters, and different conventions.

AGENTS.md solves this with Hierarchical Resolution using a "closest file wins" approach:

textCopy
1my-monorepo/
2├── AGENTS.md                 ← Global repo-wide rules
3├── apps/
4│   ├── web/
5│   │   ├── AGENTS.md         ← Rules specific to Next.js frontend
6│   │   └── src/
7│   └── api/
8│       ├── AGENTS.md         ← Rules specific to Go / gRPC backend
9│       └── main.go
10├── packages/
11│   └── shared/
12│       └── AGENTS.md         ← Rules for shared packages

When an agent works on apps/api/main.go:

1. It reads the root AGENTS.md for baseline global policies.
2. It reads apps/api/AGENTS.md, applying local overrides and extensions.

Think of it like CSS specificity: specific local rules take priority over broad global ones.

---

Anatomy of a Great AGENTS.md: The 6 Core Sections

The AAIF spec intentionally chose plain Markdown — no YAML frontmatter, no JSON schemas, no weird templating. Just standard Markdown. If you can format a README, you already know how to write an AGENTS.md.

Across thousands of production repositories, effective AGENTS.md files focus on 6 key sections:

1. 🏗️ Architecture Overview

Give a brief (1–2 paragraphs max) breakdown of the codebase layout. Essential for monorepos.

markdownCopy
1# Architecture
2TypeScript monorepo.
3- `packages/core` — core domain logic (zero DOM dependencies).
4- `apps/web` — Next.js 15 App Router (UI presentation layer only).
5- `apps/api` — Express + tRPC API Gateway.

2. 🔧 Tech Stack & Tooling

Be unambiguous about your tooling. Never let the agent guess package managers or formatters.

markdownCopy
1# Stack & Tooling
2- Package Manager: ONLY `pnpm`. NEVER run `npm` or `yarn`.
3- Code Formatting: Biome (DO NOT use Prettier or ESLint).
4- State: Zustand for client state, TanStack Query for server state.

3. ⚡ CLI Recipes

Give exact terminal commands — ready-to-run recipes the agent can execute directly.

markdownCopy
1# Commands
2- Install: `pnpm install`
3- Build: `pnpm build`
4- Run All Tests: `pnpm test`
5- Run Single Test: `pnpm test -- path/to/file.test.ts`
6- Lint & Format: `pnpm lint && pnpm format:check`

4. 📐 Coding Standards (Show, Don't Tell)

Use concrete code comparisons (❌ BAD vs. ✅ GOOD) instead of vague instructions.

markdownCopy
1# Standards
2All API handlers must return a `Result<T, E>` wrapper. Never throw raw exceptions.
3
4❌ BAD:
5try { await fetchUser(); } catch (e) { console.log(e); }
6
7✅ GOOD:
8const result = await fetchUser();
9if (!result.ok) { logger.error('Fetch failed', { err: result.error }); return null; }

5. 🚫 Red Lines (Off-Limits Boundaries)

Spell out what the agent is strictly forbidden to touch or alter. This is your safety net.

markdownCopy
1# Red Lines
2- NEVER hand-edit files in `src/generated/`.
3- NEVER delete or disable existing tests.
4- DO NOT install new npm packages without user confirmation.
5- DO NOT touch CI/CD pipeline scripts (`.github/workflows/`).

6. ✅ Verification Checklist

Define exact criteria for when a task is considered "done."

markdownCopy
1# Verification
2Before marking any task complete, you MUST execute:
31. `pnpm typecheck` — zero TypeScript errors.
42. `pnpm test` for modified packages — all green.
53. `pnpm lint` — zero linter warnings.

---

Practical Rules for Writing AGENTS.md That Actually Work

Rule 1: Respect the Context Budget

The most common trap developers fall into is dumping their team's entire Notion wiki into AGENTS.md: 50 pages of code style, full API references, and architectural RFCs from 2022.

Aim for 50 to 200 lines.

Why does this matter? Every line in AGENTS.md is loaded into every single LLM request. A 2,000-line file doesn't just burn money on tokens — it actively degrades model performance. The LLM suffers from attention dilution and starts missing both your constraints and the actual code changes.

Think of it like giving a new developer a 300-page manual on their first morning and expecting them to remember every sentence. They won't, and neither will an LLM.

Rule 2: Code Snippets Beat Paragraphs

LLMs parse real code examples infinitely better than long descriptive prose.

❌ Vague instruction:

"Write clean, robust code with good error handling and modular React hooks."

What does "clean" mean in your project? The model has no idea.

✅ Actionable instruction:

Provide side-by-side ❌ BAD and ✅ GOOD code blocks. The agent will mirror the good pattern immediately.

Rule 3: Use Hard Imperatives

Save polite phrasing for code reviews. Vague suggestions ("preferably", "if possible", "we recommend") lead to inconsistent agent output.

❌ Weak & Vague	✅ Hard Imperative
"It would be nice to use TypeScript strict mode"	"Use TypeScript strict mode. Always."
"Try to add unit tests where appropriate"	"Write a unit test for every exported function."
"Preferably avoid modifying generated files"	"NEVER edit files in src/generated/."

Rule 4: Omit Default Knowledge

There's zero reason to instruct an agent to "Use descriptive variable names" or "Use async/await for asynchronous code." Modern LLMs (Claude Opus, Gemini 3.6 Flash, GPT-5.6) already know general language conventions.

Focus exclusively on what is unique to your codebase: non-standard patterns, custom wrappers, and local constraints.

---

Anti-Patterns: Common AGENTS.md Mistakes

mermaidCopy
1flowchart TD
2    Anti["AGENTS.md Anti-Patterns"]
3    Anti --> B["Prompt Bloat<br/>(2000+ lines of noise)"]
4    Anti --> M["README Confusion<br/>(Marketing + HR onboarding)"]
5    Anti --> S["Secrets in Git<br/>(API keys committed)"]
6    Anti --> V["Fluffy Rules<br/>('write elegant code')"]
7    Anti --> St["Stale Rules<br/>(outdated instructions)"]

❌ Prompt Bloat

Pasting full linter configs, 30-page coding standards, and outdated RFCs into AGENTS.md. The model gets overwhelmed and ignores your actual instructions.

❌ README Confusion

Including OS setup guides ("First, install Homebrew...") or links to HR wiki pages. The AI agent doesn't need developer onboarding — it needs execution constraints.

❌ Committing Secrets

Accidentally leaving staging passwords, Slack webhook tokens, or API keys in AGENTS.md. Since AGENTS.md lives in Git, those secrets are committed forever.

❌ Unresolved Monorepo Conflicts

Root AGENTS.md says "Use Jest", while apps/web/AGENTS.md says "Use Vitest". Without explicit scoping, the agent generates a broken hybrid setup that fails on both runners. (Fix: explicitly state "This directory overrides root test runner to Vitest").

❌ Stale Instructions

You migrated from REST to gRPC two months ago, but AGENTS.md still says "All endpoints must use Express Router." The agent will keep writing Express routes that break your build.

Rule of thumb: Treat AGENTS.md like live production code. After any major refactor, check whether your agent instructions need an update.

---

How to Bootstrap Your AGENTS.md Fast

You don't need to craft an AGENTS.md from a blank file. Here are two practical ways developers set up their initial file:

1. Let Your AI Agent Draft It (Most Popular)

The fastest path is asking your AI assistant (Cursor, Claude Code, Gemini CLI, ChatGPT) to analyze your repo:

Prompt: "Scan my repository structure, dependencies, and build/test scripts. Generate a concise, 100-line AGENTS.md following the AAIF standard. Include commands for building, testing, linting, and our main project conventions."

2. Lightweight CLI Tools

• agentseed — an open-source CLI scanner that inspects your repo structure to generate a starter AGENTS.md with detected build and test commands.

  bashCopy
  1npx agentseed init

⚠️ Remember: Auto-generated drafts are just a starting point. Always review the file manually to strip out noise and add your team's real, non-negotiable boundaries.

---

Summary Checklist for AGENTS.md

AGENTS.md isn't just another configuration file. It's an operational contract between you and your AI coding agent. It determines whether your assistant writes clean, team-aligned code on the first try — or generates alien boilerplate that wastes your time and token budget.

Before committing your AGENTS.md, check off these items:

• Length — Kept under 200 lines (split into nested files if larger).
• Tone — Uses hard imperatives ("ALWAYS", "NEVER"), avoiding weak suggestions.
• Commands — Contains exact CLI recipes for building, testing, and linting.
• Red Lines — Explicitly lists off-limits files, folders, and actions.
• Examples — Includes concrete ❌ BAD vs. ✅ GOOD code snippets.
• Security — Zero API keys, tokens, or credentials included.
• Relevance — Omits generic language rules that LLMs already know.
• Freshness — Accurately reflects your current codebase state.

Writing an AGENTS.md brings a surprising bonus: as you formalize rules for your AI agent, you crystalize your team's engineering culture. Those implicit conventions that used to live only in senior devs' heads suddenly become clear, written standards.

That's the true power of AGENTS.md — it makes your engineering rules explicit. For machines, and for human teammates alike.

---

Resources & Links

Resource	Link
🌐 AGENTS.md Official Site	agents.md
📦 AGENTS.md Specification Repo	github.com/agentsmd/agents.md
🏛️ Agentic AI Foundation (AAIF)	aaif.io
🔧 agentseed CLI Generator	github.com/avinshe/agentseed
📖 OpenAI Platform Docs	platform.openai.com/docs
📖 Cursor AI Rules Docs	cursor.com
📖 Aider Conventions Docs	aider.chat/docs/usage/conventions
📖 Zed AI Docs	zed.dev/docs/assistant
📖 GitHub Copilot Coding Agent	gh.io/coding-agent-docs
📖 Gemini CLI Configuration	github.com/google-gemini/gemini-cli
📖 Goose (Block / AAIF)	github.com/aaif-goose/goose
🔍 Search Repositories Using AGENTS.md	GitHub Search: AGENTS.md

Introduction: Why is everyone obsessed with agent autonomy?

Just a few years ago, it seemed like AI was only good for writing rhymes and fixing syntax errors. Today, every second developer is trying to bolt all sorts of "junk" onto their AI agent and, of course, wire it directly to production servers. "Let it deploy everything itself, I'm going to scroll TikTok!" — a brilliant plan, reliable as a Swiss watch, which usually ends with a dropped database and a developer nursing a nervous tic.

These "brilliant plans" have led the industry to try and control this chaos (or at least shift the responsibility from the LLMs to us). For AI to actually do things without blowing up the system, it needs targeted, secure access. That's exactly why giants like Anthropic and GitHub have highlighted three distinct access approaches: MCP (Model Context Protocol), Skills, and Subagents.

If you read IT forums, it feels like these are competitors fighting for your access rights: "I already have MCP installed, why would I add some Skills?". Let me be honest right away: the "either/or" choice doesn't work here at all.

In a normal, secure workflow, you will definitely need all three tools. Let's break down why you need them, and why your favorite agent is still acting dumb.

---

1. MCP: The Single Protocol for External APIs

Essentially, MCP is a standardized integration protocol. The industry just agreed: "Stop making every agent write custom crutches for every new service; let's build one pipe for everyone."

How it works in reality: you run a background server (a daemon) on your local machine. Let's say you install the official github-mcp. This server hangs in memory and greets your editor: "Hello, I can create Pull Requests and read issues." The agent goes: "Cool, let's do it," and they start tossing JSONs back and forth.

What are the pros? If you need to pull massive chunks of data from Stripe, Slack, or Postgres—it's perfect. MCP handles all the headache with OAuth, tokens, and rate limits.

Where does the pain start? (Security) It's a total "black box". To install it, you often type a magic npx @some-guy/mcp-server-tools in the terminal. This unknown process gets file system access, runs in the background FOREVER, and holds your passwords in memory. It's a direct path to a supply chain attack simply because you wanted the AI agent to "format text nicely". For massive tasks like databases—it's super. But for tiny local operations—it's a security hole.

---

2. Skills: Local Scripts Without the Magic

This is where Skills enter the arena—your own local scripts that work exactly as you wrote them, not a drop more.

A Skill is not a protocol, not a server, and not a daemon. It is a profoundly simple but massively effective thing. It's literally an ordinary folder on your laptop. Inside, there's a text file SKILL.md saying "When I ask you to deploy, use this tool," and next to it—a completely standard bash script or script.js.

Scenario: You tell the agent: "Audit the project." It reads the markdown from Skills, runs your audit.sh through the terminal, waits for the result, reads it from the console, and... the script terminates. No background daemons holding onto passwords in memory. Job done—go take a walk.

Why is it cool? Because you can read the code with your own eyes. If the agent makes a mistake, it won't delete your System32 folder because your personal script strictly says "read files only". Use Skills for specific, dirty local work (running tests, building for a tricky server). This gives you 100% control and zero framework magic.

---

3. Subagents: Delegating Intellect

And now we get to the good stuff. Subagents are an architectural approach where your main AI agent doesn't do the dirty intellectual work itself, but instead hires isolated "micro-agents".

Imagine you ask the AI: "Find me info about the React 19 update on three different sites, analyze 10 pages, and write me a report." If a naive agent tries to read all those kilobytes of HTML code and dumps the garbage into your current chat—the chat will just burst. The agent will suffer a context overflow and start hallucinating hard.

How do Subagents solve this? The main agent says: "I'm the architect here, I'm not going to dig through this HTML trash myself." It quietly pushes a Researcher subagent into an isolated background environment. The subagent downloads the sites, runs the parsing (or passes it through a cheap LLM model), and returns a clean, concentrated two-paragraph JSON conclusion to the central boss.

1. Clean context. The main chat stays clean; there are no kilobytes of minified JS code from an Indian dev's StackOverflow page.
2. Security. We never give the scraper subagent write permissions to files or the database. Its only job is to "read the internet". The danger is reduced to zero.
3. Concurrency. You can send one subagent to google, and another to dig through hundreds of files of legacy code. While you go drink coffee.

---

Practice: How to Create Your Own Subagent?

Many people think creating a subagent means writing a thousand-line editor plugin. In reality, you can build an isolated subagent to handle the dirty work in literally 5 minutes using a Skill script. This is the most viable approach today.

Here is a step-by-step example: creating a Node.js scraper subagent.

Step 1. SKILL.md — instructions for the main agent

Create a .skills/scraper/ folder in your project and drop a SKILL.md inside. This is exactly where your main AI assistant learns it has a new employee.

markdownCopy
1# Scraper Subagent
2
3## When to use
4This is your local parsing tool. Use it whenever you need to:
5- Visit an external website and read its content.
6Do not try to load the site yourself in the chat, delegate this work to the subagent.
7
8## How to call
9```bash
10node .skills/scraper/index.js ""
11```
12
13## Response format
14The subagent will return a ready-to-use parsed JSON in stdout:
15```json
16{ "title": "...", "text": "Clean text without tags" }
17```

Step 2. index.js — the subagent's logic

And here is the "brain" of the subagent going out to do the dirty work:

javascriptCopy
1// .skills/scraper/index.js
2import fetch from 'node-fetch';
3import * as cheerio from 'cheerio';
4
5const url = process.argv[2];
6
7async function runSubagent() {
8    // console.error — used strictly for logging (the agent ignores this and doesn't pull it into context)
9    console.error(`[Scraper Subagent] The boss said to go parse HTML: ${url}`);
10    
11    // 1. Hit the network and pull the heavy document
12    const response = await fetch(url, { headers: { 'User-Agent': 'Mozilla/5.0' } });
13    const html = await response.text();
14
15    // 2. Isolated data processing 
16    const $ = cheerio.load(html);
17    $('script, style, nav, footer').remove(); // Bin the trash
18    const cleanText = $('body').text().replace(/\s+/g, ' ').trim().slice(0, 4000);
19
20    const result = { 
21        status: "success", 
22        title: $('title').text().trim(), 
23        text: cleanText 
24    };
25
26    // 3. Spit the result out to the main agent via stdout
27    console.log(JSON.stringify(result));
28}
29
30runSubagent();

What happens in practice? The main agent receives a task with a link from you. It sees it has a helper in the form of a skill, spawns a Node process in a background terminal, and drops the URL there. Your Node subagent—isolated, without clogging the main chat's memory with garbage—downloads hundreds of HTML kilobytes, cleans them up, and returns a pristine JSON to the central boss.

Congratulations, you just quickly implemented a simple microservices architecture for your AI.

---

Who Actually Supports All This? (Ecosystem Cheat Sheet)

Theory sorted, but where do we shove all this? In 2026, every editor or client offers its own implementation. To save you from reading tons of documentation and racking your brain, here's a quick table:

Tool / IDE	MCP (Global Server)	Skills (Local Scripts)	Subagents (Delegation)	How to set up?
Cursor	✅ Native, click-click	⚠️ Via workaround	❌ Not supported directly	Add MCP via Settings -> Features -> MCP Server. To force it to see Skills, you must enforce in .cursorrules: "Always read instructions from scripts in the .skills/ folder".
Claude Code (cli)	✅ Native	✅ Its native home	❌ Not out of the box	MCP is configured via config file. Console geeks will be happy: Skills just sit in a local folder—the client finds and comprehends them automatically as a core feature.
Claude Desktop	✅ Native and powerful	❌ Can't do it at all	❌ None	Register paths in claude_desktop_config.json. It simply doesn't pull local bash scripts (Skills) and subagents yet.
GitHub Copilot	⚠️ Currently an experiment	❌ Not supported	✅ Native (ideal)	Subagents are built-in out of the box (e.g., @workspace, @terminal, or your custom agents via API). Brilliantly done for delegating tasks and exploring code without cluttering the main chat's brain.
Roo Code (VS Code)	✅ Native, convenient	⚠️ Via workaround	⚠️ Via agent "Roles"	Add MCP directly in the GUI. For full-scale subagents, it allows configuring 'Custom Modes'—restricted roles you can switch between.
Windsurf	✅ Native	❌ Better not to bother	❌ None	Add MCP directly in graphical settings. It's too early to poke it with custom scripts.

Quick ecosystem takeaway: MCP is already the global, inevitable integration standard. Skills are more of a feature for those who want strict control over local scripts (Claude Code leads here). But Subagents are the obvious trend for complex multi-step development, currently working natively best within the Copilot system.

---

Conclusion: So What Should I Use?

Remember a simple rule, and your AI assistants will stop ruining your life:

1. Need to talk to an external system (Stripe, GitHub, Supabase)? Grab MCP. Let competent developers and a ready-made server handle the authorization and protocols; don't poke around there yourself.
2. Need to do something on your local machine (run isolated tests, copy files)? Write your own Skill. You can see your bash script yourself, and it's safer than giving a stranger's npm package root access to your machine.
3. Need to execute heavy research work (download five sites, analyze tons of legacy code, and return JSON)? Implement a Subagent. Offload the heavy lifting to an isolated "micro-agent" and protect your main chat's sanity.

Don't give unknown, third-party processes full access to your computer just to wait for surprises from random npm packages. Your codebase will thank you.

---

What you'll learn: How to build AI agent systems with LangGraph - from basic concepts to working code. We'll create an article-writing pipeline with multiple AI agents that collaborate, review each other's work, and iterate until the result is perfect.

---

PART 1: Basic Concepts

What is a Graph?

Before diving into LangGraph, it's essential to understand what a graph is in programming.

A Graph is a Data Structure

Imagine a subway map:

• Stations are the nodes
• Lines between stations are the edges

textCopy
1    Typical Graph:              Subway Map (Analogy):
2
3        [A]                         [Victory Square]
4         │                                 │
5         ▼                                 ▼
6        [B]───────►[C]              [October]───►[Kupala]
7         │                                 │
8         ▼                                 ▼
9        [D]                         [Cultural Institute]

In LangGraph:

• Nodes are functions (agents) that perform tasks.
• Edges are rules indicating the order in which tasks are executed.

---

Why is LangGraph Needed?

Problem: Traditional AI Programs are Linear

textCopy
1Typical Chain:
2
3    Question → LLM → Answer
4
5    or
6
7    Question → Tool 1 → LLM → Tool 2 → Answer

This works for simple tasks, but what if:

• You need to go back and redo something?
• You need to verify the result and possibly repeat?
• You need multiple agents with different roles?

Solution: LangGraph Allows Creating Cycles

textCopy
1LangGraph (Graph):
2
3                    ┌──────────────────────┐
4                    │                      │
5                    ▼                      │
6    Question → [Researcher] → [Writer] → [Reviewer]
7                                               │
8                                               ▼
9                                          Good? ───NO───► back to Writer
10                                               │
11                                              YES
12                                               │
13                                               ▼
14                                           [Result]

---

What is "state"?

State is the memory of the program.

Imagine you are writing an article with a team:

• The researcher gathered materials → needs to write them down somewhere.
• The writer created a draft → needs to pass it to the reviewer.
• The reviewer wrote comments → needs to return them to the writer.

State is like a "basket" where everyone puts their results and from which they take data.

textCopy
1┌─────────────────────────────────────────────────────────────┐
2│                        STATE (Стан)                         │
3├─────────────────────────────────────────────────────────────┤
4│                                                             │
5│   topic: "What I Write"                                     │
6│   research: "Materials from the Researcher"                 │
7│   draft: "Draft from the Writer"                            │
8│   review: "Comments from the Reviewer"                      │
9│   finalArticle: "Final Article"                             │
10│   messages: [history of all messages]                       │
11│                                                             │
12└─────────────────────────────────────────────────────────────┘
13              ▲               ▲               ▲
14              │               │               │
15         Researcher        Writer         Reviewer
16      (reads and writes) (reads and writes) (reads and writes)

---

PART 2: Annotation - How State is Created

What is Annotation?

Annotation is a way of describing the structure of a state. It is like creating a form with fields.

Analogy: Survey

Imagine you are creating a survey:

textCopy
1┌─────────────────────────────────────────┐
2│            EMPLOYEE SURVEY              │
3├─────────────────────────────────────────┤
4│ Name: ___________________               │
5│ Age: _____                              │
6│ Work Experience (years): _____          │
7│ Skills List: ___, ___, ___              │
8└─────────────────────────────────────────┘

In code, it looks like this:

typescriptCopy
1// ANALOGY: Creating a survey form
2const Survey = {
3    name: '', // Text field
4    age: 0, // Number
5    experience: 0, // Number
6    skills: [], // List
7};

In LangGraph: Annotation.Root

In LangGraph, state is created using Annotation.Root(). This is a special function that describes the structure of your data - what fields exist and how they should be updated.

typescriptCopy
1import { Annotation } from '@langchain/langgraph';
2
3const ResearchState = Annotation.Root({
4    // Each field is described through Annotation<Type>
5    topic: Annotation<string>({...}),
6    research: Annotation<string>({...}),
7    draft: Annotation<string>({...}),
8    // etc.
9});

Each field inside Annotation.Root has two important properties: reducer (how to update the value) and default (initial value). We'll explore these next.

---

What is a Reducer?

Problem: How to merge data?

What should you do when multiple agents write to the same field?

textCopy
1Agent 1 writes: topic = "Topic A"
2Agent 2 writes: topic = "Topic B"
3
4What should be in topic? "Topic A"? "Topic B"? "Topic A + Topic B"?

Solution: Reducer - a function that resolves

Reducer is a function that takes:

1. Current value (what is already there)
2. New Value (what comes in)

It returns: result (what to keep)

typescriptCopy
1reducer: (current, update) => result;
2//         ▲         ▲           ▲
3//         │         │           └── What will be kept
4//         │         └── New value
5//         └── Current value

Examples of Reducers:

1. Reducer "REPLACE"

The new value completely replaces the old one.

typescriptCopy
1// Code:
2reducer: (current, update) => update;
3
4// Example:
5// Current: "Theme A"
6// New:     "Theme B"
7// Result:   "Theme B"  ← new replaces old

Analogy: You overwrite a file - the new content replaces the old one.

textCopy
1file.txt
2──────────────
3Was:   "Old text"
4        ▼ (overwrite)
5Is:    "New text"

2. Reducer "APPEND"

New elements are added to the existing ones.

typescriptCopy
1// Code:
2reducer: (current, update) => [...current, ...update];
3
4// Example:
5// Current: ["Message 1", "Message 2"]
6// New:     ["Message 3"]
7// Result:   ["Message 1", "Message 2", "Message 3"]

Analogy: You add new entries to a diary - the old ones remain.

textCopy
1diary.txt
2──────────────
3Was:    "Monday: did A"
4        "Tuesday: did B"
5             ▼ (adding)
6Became: "Monday: did A"
7        "Tuesday: did B"
8        "Wednesday: did C" ← added

Full example of the state:

typescriptCopy
1const ResearchState = Annotation.Root({
2    // ═══════════════════════════════════════════════════════
3    // FIELD: messages (messages)
4    // ═══════════════════════════════════════════════════════
5    messages: Annotation<BaseMessage[]>({
6        // REDUCER: Add new messages to existing ones
7        reducer: (current, update) => [...current, ...update],
8        // DEFAULT: Initial value - empty array
9        default: () => [],
10    }),
11    //
12    // How it works:
13    // 1. Beginning:    messages = []
14    // 2. Researcher:  messages = [] + [AIMessage] = [AIMessage]
15    // 3. Writer: messages = [AIMessage] + [AIMessage] = [AIMessage, AIMessage]
16    // 4. And so on - all messages are stored
17
18    // ═══════════════════════════════════════════════════════
19    // FIELD: topic (topic)
20    // ═══════════════════════════════════════════════════════
21    topic: Annotation<string>({
22        // REDUCER: Replace old value with new one
23        reducer: (_, update) => update, // "_" means "ignore"
24        default: () => '',
25    }),
26    //
27    // How it works:
28    // 1. Beginning:    topic = ""
29    // 2. User:   topic = "" → "LangChain"
30    // If someone else writes in topic - the old value will disappear
31
32    // ═══════════════════════════════════════════════════════
33    // FIELD: iterationCount (iteration counter)
34    // ═══════════════════════════════════════════════════════
35    iterationCount: Annotation<number>({
36        reducer: (_, update) => update, // Simply replace
37        default: () => 0, // Start from 0
38    }),
39    //
40    // The writer writes each time: iterationCount: state.iterationCount + 1
41    // 1. Start:         iterationCount = 0
42    // 2. Writer (1):   iterationCount = 0 + 1 = 1
43    // 3. Writer (2):   iterationCount = 1 + 1 = 2
44    // 4. Writer (3): iterationCount = 2 + 1 = 3
45});

Visualization of Reducers:

textCopy
1┌─────────────────────────────────────────────────────────────────┐
2│                       REDUCER: REPLACE                          │
3├─────────────────────────────────────────────────────────────────┤
4│                                                                 │
5│   Current: █████████████  "Old text"                            │
6│                  ▼                                              │
7│   New:     ░░░░░░░░░░░░░  "New text"                            │
8│                  ▼                                              │
9│   Result:  ░░░░░░░░░░░░░  "New text" ← only new                 │
10│                                                                 │
11└─────────────────────────────────────────────────────────────────┘
12
13┌─────────────────────────────────────────────────────────────────┐
14│                         REDUCER: ADD                            │
15├─────────────────────────────────────────────────────────────────┤
16│                                                                 │
17│   Current:  [█] [█] [█]      ← three elements                   │
18│                  +                                              │
19│   New:      [░] [░]          ← two new                          │
20│                  =                                              │
21│   Result:   [█] [█] [█] [░] [░]  ← all together                 │
22│                                                                 │
23└─────────────────────────────────────────────────────────────────┘

---

What is default?

default is a function that returns the initial value of a field.

typescriptCopy
1default: () => value

Why a function and not just a value?

This is a common JavaScript pitfall. If you use a plain object or array as default, all instances will share the same reference - changes in one place will affect all others!

typescriptCopy
1// POOR: If this is an object or array
2default: []  // All instances will refer to the same array!
3
4// GOOD: The function creates a new array each time
5default: () => []  // Each instance will get its own array

Examples:

typescriptCopy
1// For a string
2default: () => ''        // Empty string
3
4// For a number
5default: () => 0         // Zero
6
7// For an array
8default: () => []        // Empty array
9
10// For an object
11default: () => ({})      // Empty object
12
13// For boolean
14default: () => false     // false

---

PART 3: Nodes - Agents

What is a node?

Node is a function that:

1. Receives the full state
2. Performs some work (for example, calls LLM)
3. Returns a partial state update

Analogy: Worker on the Assembly Line

textCopy
1┌─────────────────────────────────────────────────────────────┐
2│                       ASSEMBLY LINE                         │
3├─────────────────────────────────────────────────────────────┤
4│                                                             │
5│   [Box] ──► [Worker 1] ───────► [Worker 2] ──────►          │
6│                  │                    │                     │
7│                  ▼                    ▼                     │
8│            Adds part A          Adds part B                 │
9│                                                             │
10└─────────────────────────────────────────────────────────────┘
11
12Each worker:
131. Sees what has already been done (state)
142. Does their part of the work
153. Passes it on with additions

Node Structure in Code:

typescriptCopy
1async function myNode(
2    state: ResearchStateType // ← INPUT: Full state
3): Promise<Partial<ResearchStateType>> {
4    // ← OUTPUT: Partial update
5    // 1. Read data from state
6    const data = state.someField;
7
8    // 2. Do the work
9    const result = await doSomething(data);
10
11    // 3. Returning the update (only what has changed)
12    return {
13        someField: result,
14    };
15}

Important: Partial<State>

A node doesn't need to return the entire state - only the fields that changed. LangGraph will merge your partial update with the existing state using the reducers you defined.

typescriptCopy
1// The full state has 6 fields:
2state = {
3    topic: "...",
4    research: "...",
5    draft: "...",
6    review: "...",
7    finalArticle: "...",
8    messages: [...],
9    iterationCount: 0
10}
11
12// But the node can only return what it has changed:
13return {
14    draft: "New draft",           // Changed
15    messages: [new AIMessage("...")], // Added
16    // The other fields are not mentioned - they will remain as they were
17}

---

Our nodes in detail

Now let's look at the four nodes in our article-writing system. Each node has a specific role and passes its results to the next one through the shared state.

Node 1: Researcher (researcherNode)

The researcher is the first agent in our pipeline. It takes the topic and generates research materials that will be used by the writer.

typescriptCopy
1async function researcherNode(
2    state: ResearchStateType
3): Promise<Partial<ResearchStateType>> {
4    // ┌─────────────────────────────────────────────────────────────┐
5    // │ STEP 1: Get the topic for research                         │
6    // └─────────────────────────────────────────────────────────────┘
7    const topic =
8        state.topic ||
9        String(state.messages[state.messages.length - 1]?.content) ||
10        '';
11    //            ▲               ▲
12    //            │               └── Or the last message
13    //            └── First, try to take topic
14
15    // ┌─────────────────────────────────────────────────────────────┐
16    // │ STEP 2: Form the prompt for LLM                            │
17    // └─────────────────────────────────────────────────────────────┘
18    const prompt = `You are an expert researcher. Your task is to gather key information.
19    Topic: ${topic}
20    Conduct a brief research...`;
21
22    // ┌─────────────────────────────────────────────────────────────┐
23    // │ STEP 3: Call LLM                                           │
24    // └─────────────────────────────────────────────────────────────┘
25    const response = await model.invoke([
26        { role: 'system', content: prompt }, // Instructions for AI
27        { role: 'user', content: `Research the topic: ${topic}` }, // Request
28    ]);
29
30    const research = String(response.content); // Result from LLM
31
32    // ┌─────────────────────────────────────────────────────────────┐
33    // │ STEP 4: Return state update                                │
34    // └─────────────────────────────────────────────────────────────┘
35    return {
36        research, // Store the research result
37        messages: [
38            new AIMessage({
39                content: `[Research completed]
40${research}`,
41            }),
42        ],
43        // ▲ Add a message to the history
44    };
45}

What happens:

textCopy
1INPUT (state):                       OUTPUT (update):
2┌─────────────────────┐              ┌─────────────────────┐
3│ topic: "LangChain"  │              │ research: "LangCh.. │
4│ research: ""        │  ──────►     │ messages: [+1 msg]  │
5│ draft: ""           │              └─────────────────────┘
6│ messages: [1 msg]   │
7└─────────────────────┘
8                                     ▼ After merging:
9
10                                ┌─────────────────────┐
11                                │ topic: "LangChain"  │
12                                │ research: "LangCh...│ ← updated
13                                │ draft: ""           │
14                                │ messages: [2 msgs]  │ ← added
15                                └─────────────────────┘

---

Node 2: Writer (writerNode)

The writer takes the research and creates an article draft. If this is a revision (after reviewer feedback), it also considers the review comments. Notice how iterationCount helps us track how many times the article has been rewritten.

typescriptCopy
1async function writerNode(
2    state: ResearchStateType
3): Promise<Partial<ResearchStateType>> {
4    // ┌─────────────────────────────────────────────────────────────┐
5    // │ STEP 1: Read the research and possible review              │
6    // └─────────────────────────────────────────────────────────────┘
7    const prompt = `You are a technical writer. Based on the research, write an article.
8
9Research:
10${state.research}
11
12${state.review ? `Previous review (consider comments): ${state.review}` : ''}
13`;
14
15    // ┌─────────────────────────────────────────────────────────────┐
16    // │ STEP 2: Call LLM                                           │
17    // └─────────────────────────────────────────────────────────────┘
18    const response = await model.invoke([
19        { role: 'system', content: prompt },
20        { role: 'user', content: 'Write an article based on the research' },
21    ]);
22
23    const draft = String(response.content);
24
25    // ┌─────────────────────────────────────────────────────────────┐
26    // │ STEP 3: Return the update                                  │
27    // └─────────────────────────────────────────────────────────────┘
28    return {
29        draft, // Draft of the article
30        iterationCount: state.iterationCount + 1, // Increment the counter
31        messages: [
32            new AIMessage({ content: `[Draft ${state.iterationCount + 1}]` }),
33        ],
34    };
35}

What happens on repeat call:

textCopy
1FIRST CALL:                          SECOND CALL (after review):
2┌─────────────────────┐              ┌─────────────────────┐
3│ research: "..."     │              │ research: "..."     │
4│ review: ""          │              │ review: "Refine..." │ ← there are comments!
5│ iterationCount: 0   │              │ iterationCount: 1   │
6└─────────────────────┘              └─────────────────────┘
7         │                                    │
8         ▼                                    ▼
9Writing without comments             Considering comments
10         │                                    │
11         ▼                                    ▼
12┌─────────────────────┐              ┌─────────────────────┐
13│ draft: "Version 1"  │              │ draft: "Version 2"  │
14│ iterationCount: 1   │              │ iterationCount: 2   │
15└─────────────────────┘              └─────────────────────┘

---

Node 3: Reviewer (reviewerNode)

The reviewer evaluates the draft and decides if it's ready for publication. The key here is the output: if the review contains "APPROVED", the article moves to finalization. Otherwise, it goes back to the writer for improvements. This is what enables the cycle in our graph.

typescriptCopy
1async function reviewerNode(state: ResearchStateType): Promise<Partial<ResearchStateType>> {
2
3    // ┌─────────────────────────────────────────────────────────────┐
4    // │ STEP 1: Formulating the review request                      │
5    // └─────────────────────────────────────────────────────────────┘
6    const prompt = `You are a strict editor. Evaluate the article.
7
8Article:
9${state.draft}
10
11Evaluate based on the criteria:
121. Accuracy of information
132. Structure and logic
143. Language quality
154. Completeness of the topic coverage
16
17If the article is good - say "APPROVED". When improvements are needed, please provide specific recommendations.
18`;
19
20    // ┌─────────────────────────────────────────────────────────────┐
21    // │ STEP 2: Get the review                                     │
22    // └─────────────────────────────────────────────────────────────┘
23    const response = await model.invoke([...]);
24    const review = String(response.content);
25
26    // ┌─────────────────────────────────────────────────────────────┐
27    // │ STEP 3: Return the review                                  │
28    // └─────────────────────────────────────────────────────────────┘
29    return {
30        review,  // Review (either "APPROVED" or comments)
31        messages: [new AIMessage({ content: `[Review]\n${review}` })],
32    };
33}

Two possible outcomes:

textCopy
1OPTION A: The article is good             OPTION B: Needs improvement
2┌───────────────────────────┐             ┌───────────────────────────┐
3│ review: "APPROVED.        │             │ review: "Improve:         │
4│ The article is excellent!"│             │ 1. Add examples           │
5│                           │             │ 2. Clarify the terms"     │
6└───────────────────────────┘             └───────────────────────────┘
7             │                                        │
8             ▼                                        ▼
9        Moving to                              Returning to
10        finalizer                                 writer

---

Node 4: Finalizer (finalizerNode)

The finalizer is the simplest node - it just copies the approved draft to the finalArticle field, marking the end of our workflow. This is called when the reviewer approves the article.

typescriptCopy
1async function finalizerNode(
2    state: ResearchStateType
3): Promise<Partial<ResearchStateType>> {
4    // Simple node - copies the draft to the final article
5    return {
6        finalArticle: state.draft, // Final article
7        messages: [new AIMessage({ content: `[READY]\n\n${state.draft}` })],
8    };
9}

What happens:

textCopy
1INPUT:                              OUTPUT:
2┌─────────────────────┐             ┌─────────────────────┐
3│ draft: "Ready..."   │  ──────►    │ finalArticle:       │
4│ finalArticle: ""    │             │   "Ready..."        │
5└─────────────────────┘             └─────────────────────┘

---

PART 4: Edges

What is an edge?

Edge is a rule that states: "After this node, the following node is executed."

Analogy: Arrows on the Diagram

textCopy
1Recipe steps:
2
3    [Make dough] ────► [Add sauce] ────► [Add cheese] ────► [Bake]
4          │                  │                  │               │
5          ▼                  ▼                  ▼               ▼
6      TRANSITION         TRANSITION        TRANSITION         END

Two Types of Transitions in LangGraph:

1. Simple Transitions (addEdge)

Always go to the same node.

typescriptCopy
1workflow.addEdge('researcher', 'writer');
2//                    ▲            ▲
3//                    │            └── Where are we going
4//                    └── From where are we coming
5
6// Meaning: After researcher, we ALWAYS go to writer

Visualization:

textCopy
1    [researcher] ───────────────► [writer]
2                   (always)

2. Conditional Transitions (addConditionalEdges)

The choice of the next node depends on the state.

typescriptCopy
1workflow.addConditionalEdges(
2    'reviewer', // Source node
3    shouldContinue, // Function that decides where to go
4    {
5        writer: 'writer', // If the function returns 'writer' → go to writer
6        finalizer: 'finalizer', // If the function returns 'finalizer' → go to finalizer
7    }
8);

Visualization:

textCopy
1                            ┌──────────► [writer]
2                            │
3    [reviewer] ─────► [?] ──┤
4                            │
5                            └──────────► [finalizer]
6
7    The function shouldContinue decides which arrow to take.

---

Detailed Function shouldContinue

This is the "brain" of our conditional edge. It examines the current state and decides where to go next. The function must return a string that matches one of the keys in the mapping object we defined in addConditionalEdges.

typescriptCopy
1function shouldContinue(state: ResearchStateType): 'writer' | 'finalizer' {
2    //                                              ▲
3    //                                              └── Returns one of these strings
4
5    const review = state.review.toLowerCase();
6    const maxIterations = 3;
7
8    // ═══════════════════════════════════════════════════════════════
9    // CONDITION 1: Reviewer said "APPROVED"
10    // ═══════════════════════════════════════════════════════════════
11    if (review.includes('зацверджана') || review.includes('approved')) {
12        console.log('Article approved');
13        return 'finalizer'; // ← Proceed to finalize
14    }
15
16    // ═══════════════════════════════════════════════════════════════
17    // CONDITION 2: Too many attempts (protection against infinite loop)
18    // ═══════════════════════════════════════════════════════════════
19    if (state.iterationCount >= maxIterations) {
20        console.log('Maximum iterations reached');
21        return 'finalizer'; // ← Force finalize
22    }
23
24    // ═══════════════════════════════════════════════════════════════
25    // OTHERWISE: Needs revision
26    // ═══════════════════════════════════════════════════════════════
27    console.log('Revision needed');
28    return 'writer'; // ← Go back to writer
29}

Decision flowchart:

textCopy
1                         ┌───────────────────┐
2                         │  shouldContinue   │
3                         │    (function)     │
4                         └─────────┬─────────┘
5                                   │
6                                   ▼
7                    ┌──────────────────────────────┐
8                    │   Is "approved" present      │
9                    │   in the review?             │
10                    └──────────────┬───────────────┘
11                                   │
12                      ┌────────────┴────────────┐
13                      │                         │
14                     YES                       NO
15                      │                         │
16                      ▼                         ▼
17               ┌────────────┐      ┌──────────────────────────┐
18               │  return    │      │ Is iterationCount >= 3?  │
19               │'finalizer' │      └──────────────┬───────────┘
20               │            │                     │
21               └────────────┘        ┌────────────┴────────────┐
22                                     │                         │
23                                    YES                       NO
24                                     │                         │
25                                     ▼                         ▼
26                              ┌────────────┐            ┌────────────┐
27                              │  return    │            │  return    │
28                              │'finalizer' │            │  'writer'  │
29                              │            │            │            │
30                              └────────────┘            └────────────┘

---

How the graph is built

Now let's put everything together! Building a graph in LangGraph follows a simple pattern: create the graph, add nodes, connect them with edges, and compile.

Sequence of creation:

typescriptCopy
1// ═══════════════════════════════════════════════════════════════
2// STEP 1: Create StateGraph with our state
3// ═══════════════════════════════════════════════════════════════
4const workflow = new StateGraph(ResearchState)
5
6    // ═══════════════════════════════════════════════════════════
7    // STEP 2: Add nodes (register functions)
8    // ═══════════════════════════════════════════════════════════
9    .addNode('researcher', researcherNode) // Name 'researcher' → function
10    .addNode('writer', writerNode) // Name 'writer' → function
11    .addNode('reviewer', reviewerNode) // Name 'reviewer' → function
12    .addNode('finalizer', finalizerNode) // Name 'finalizer' → function
13
14    // ═══════════════════════════════════════════════════════════
15    // STEP 3: Add simple transitions
16    // ═══════════════════════════════════════════════════════════
17    .addEdge('__start__', 'researcher') // Start → Researcher
18    .addEdge('researcher', 'writer') // Researcher → Writer
19    .addEdge('writer', 'reviewer') // Writer → Reviewer
20
21    // ═══════════════════════════════════════════════════════════
22    // STEP 4: Add conditional transition
23    // ═══════════════════════════════════════════════════════════
24    .addConditionalEdges('reviewer', shouldContinue, {
25        writer: 'writer', // If 'writer' → back to writer
26        finalizer: 'finalizer', // If 'finalizer' → to finalizer
27    })
28
29    // ═══════════════════════════════════════════════════════════
30    // STEP 5: Add final transition
31    // ═══════════════════════════════════════════════════════════
32    .addEdge('finalizer', '__end__'); // Finalizer → End

Special nodes:

textCopy
1┌───────────────┬─────────────────────────────────────────────┐
2│  '__start__'  │  Virtual start node                         │
3│               │  LangGraph automatically starts from it     │
4├───────────────┼─────────────────────────────────────────────┤
5│  '__end__'    │  Virtual end node                           │
6│               │  When reached - the graph is completed      │
7└───────────────┴─────────────────────────────────────────────┘

---

PART 5: Compilation and execution

We've defined our state, nodes, and edges. Now it's time to turn this blueprint into a running application!

What is compile()?

compile() is the process of transforming a graph description into an executable program. Until you call compile(), you just have a description of what you want to build - not an actual runnable system.

typescriptCopy
1// Graph description (blueprint)
2const workflow = new StateGraph(ResearchState)
3    .addNode(...)
4    .addEdge(...);
5
6// Compilation into an executable program
7const app = workflow.compile();
8//    ▲
9//    └── Now this can be run!

Analogy: Recipe vs. Finished Dish

textCopy
1workflow (description)                 app (compiled program)
2──────────────────────                 ──────────────────────
3Recipe on paper                        Ready pizza
4   - How to make the dough                (can be eaten)
5   - What to add
6   - How to bake
7
8Cannot be eaten!                       Can be eaten!

---

Checkpointer (MemorySaver)

What is it?

Checkpointer is a mechanism for saving state after each step.

typescriptCopy
1import { MemorySaver } from '@langchain/langgraph';
2
3const checkpointer = new MemorySaver();
4
5const app = workflow.compile({
6    checkpointer, // ← Adding checkpointer
7});

Why is this needed?

textCopy
1WITHOUT CHECKPOINTER:
2═════════════════════════════════════════════════════════════════
3
4    Run 1:   START → researcher → writer → ... → END
5
6    Run 2:   START → researcher → ... (everything from the beginning!)
7
8    ✗ Cannot continue from the stopping point
9    ✗ Cannot view history
10
11
12WITH CHECKPOINTER:
13═════════════════════════════════════════════════════════════════
14
15    Run 1:   START → researcher → [SAVED]
16                                      │
17                               thread_id: "chat-123"
18
19    Run 2:   [RESUMING] → writer → reviewer → ...
20                     │
21              thread_id: "chat-123"
22
23    ✓ Can continue from the stopping point
24    ✓ Can view history
25    ✓ Can have multiple independent "conversations"

Thread ID - identifier of the "thread"

typescriptCopy
1const config = {
2    configurable: {
3        thread_id: 'article-1', // Unique ID for this "conversation"
4    },
5};
6
7// Each thread_id is a separate story
8// 'article-1' - about one article
9// 'article-2' - about another article
10// They do not overlap!

---

Running the Graph

Finally! Let's run our graph. The invoke() function takes initial state values and configuration, then executes the entire graph from start to finish.

The invoke() Function

typescriptCopy
1const result = await app.invoke(
2    // Initial data for the state
3    {
4        topic: 'Benefits of LangChain',
5        messages: [new HumanMessage('Benefits of LangChain')],
6    },
7    // Configuration
8    {
9        configurable: {
10            thread_id: 'article-1',
11        },
12    }
13);

What Happens When invoke() is Called:

textCopy
1┌─────────────────────────────────────────────────────────────────┐
2│                         invoke()                                │
3└───────────────────────────────┬─────────────────────────────────┘
4                                │
5                                ▼
6┌─────────────────────────────────────────────────────────────────┐
7│ 1. INITIALIZATION OF STATE                                      │
8│    state = {                                                    │
9│        topic: "Advantages of LangChain",                        │
10│        messages: [HumanMessage],                                │
11│        research: "",  ← default                                 │
12│        draft: "",     ← default                                 │
13│        review: "",    ← default                                 │
14│        finalArticle: "", ← default                              │
15│        iterationCount: 0, ← default                             │
16│    }                                                            │
17└───────────────────────────────┬─────────────────────────────────┘
18                                │
19                                ▼
20┌─────────────────────────────────────────────────────────────────┐
21│ 2. BEGINNING: __start__ → researcher                            │
22│    Executing researcherNode(state)                              │
23│    → Receiving update {research: "...", messages: [...]}        │
24│    → Merging with state through reducers                        │
25│    Saving checkpoint                                            │
26└───────────────────────────────┬─────────────────────────────────┘
27                                │
28                                ▼
29┌─────────────────────────────────────────────────────────────────┐
30│ 3. TRANSITION: researcher → writer                              │
31│    Execute writerNode(state)                                    │
32│    → Receive update {draft: "...", iterationCount: 1}           │
33│    → Merge with state                                           │
34│    Save checkpoint                                              │
35└───────────────────────────────┬─────────────────────────────────┘
36                                │
37                                ▼
38┌─────────────────────────────────────────────────────────────────┐
39│ 4. TRANSITION: writer → reviewer                                │
40│    Execute reviewerNode(state)                                  │
41│    → Receive update {review: "..."}                             │
42│    → Merge with state                                           │
43│    Save checkpoint                                              │
44└───────────────────────────────┬─────────────────────────────────┘
45                                │
46                                ▼
47┌─────────────────────────────────────────────────────────────────┐
48│ 5. CONDITIONAL TRANSITION: shouldContinue(state)                │
49│    → Returns 'writer' or 'finalizer'                            │
50│    → If 'writer' - return to step 3                             │
51│    → If 'finalizer' - proceed further                           │
52└───────────────────────────────┬─────────────────────────────────┘
53                                │ (if 'finalizer')
54                                ▼
55┌─────────────────────────────────────────────────────────────────┐
56│ 6. TRANSITION: reviewer → finalizer                             │
57│    Execute finalizerNode(state)                                 │
58│    → Receive update {finalArticle: "..."}                       │
59│    → Merge with state                                           │
60│    Save checkpoint                                              │
61└───────────────────────────────┬─────────────────────────────────┘
62                                │
63                                ▼
64┌─────────────────────────────────────────────────────────────────┐
65│ 7. FINALIZER: finalizer → __end__                               │
66│    The graph has completed                                      │
67│    Returning the final state                                    │
68└───────────────────────────────┬─────────────────────────────────┘
69                                │
70                                ▼
71                        return state (full)

---

PART 6: FAQ - Frequently Asked Questions

Why does the reducer add messages but replace the topic?

Messages represent history. We want to keep all messages throughout the process.

Topic is the current theme. When the topic changes, the old one is no longer needed.

What happens if I don’t specify a reducer?

LangGraph will use the default behavior - replacement (like for the topic).

Why is iterationCount needed?

To protect against infinite loops. If the reviewer never says "approved", the program will keep cycling between the writer and the reviewer.

Can one node directly invoke another?

No. Nodes do not know about each other. They only read/write state. LangGraph determines who executes next based on transitions.

What are start and end?

These are special virtual nodes:

• __start__ - where the graph begins
• __end__ - where the graph ends

They do not execute code - they only mark the boundaries.

Can there be multiple end nodes?

Yes! For example:

typescriptCopy
1.addEdge('success', '__end__')
2.addEdge('error', '__end__')

---

Conclusion

Congratulations! You've learned the core concepts of LangGraph. Let's recap what we covered:

Concept	What it does
State + Annotation	Defines the data structure passed between agents
Reducer	Specifies how to combine new data with existing data
Nodes (Agents)	Functions that process the state
Edges (Transitions)	Rules determining the order of operations
Conditional Edges	Dynamic selection of the next node
Checkpointer	Saves the state for continuation later

What's Next?

Now that you understand the basics, you can:

1. Build your own agent system - Start with a simple two-node graph and gradually add complexity
2. Experiment with different flows - Try creating graphs with multiple conditional branches
3. Add persistence - Use MemorySaver or database-backed checkpointers for production
4. Explore advanced features - Look into subgraphs, parallel execution, and human-in-the-loop patterns

Key Takeaways

• Think in graphs: Break down your AI workflow into discrete steps (nodes) connected by rules (edges)
• State is everything: All communication between nodes happens through the shared state
• Reducers matter: Choose the right reducer for each field - append for history, replace for current values
• Cycles enable iteration: Unlike simple chains, graphs can loop back for refinement

The article-writing example we built demonstrates a real-world pattern: research → write → review → (repeat if needed) → finalize. This same pattern applies to many AI applications: code review, content moderation, multi-step reasoning, and more.

Happy building! 🚀

Greetings!
If you are tired of manually editing endless JSON files with translations and want your AI agent (Copilot, Cursor, Claude) to do it for you — this article is for you.

Today we will look at Goman.live — a tool that turns the routine of localization into magic. We will discuss why it is needed, how it saves your time, and why it is a must-have for the modern "vibe coder".

---

What is Goman.live and why do you need it?

Goman.live is not just another translator. It is a smart backend for managing your application's content.

Imagine: you write code, and all texts — buttons, errors, descriptions — automatically appear in all required languages, taking into account the context and style of your project. No manual copying to Google Translate, no errors in keys, and no "broken" localization files.

The service works in two modes:

1. Autopilot (via MCP): You simply ask your AI agent in the IDE to "add a button", and everything happens by itself.
2. Control Center (Web Editor): A powerful interface for manual tuning, quality checking, and managing complex contexts.

---

Who really needs this?

Goman.live was created to remove pain from the development process:

• 🚀 Vibe Coders (AI-Native Developers): You are used to working fast. Context switching to edit JSON kills the flow. Goman allows you not to leave the IDE.
• 👨‍💻 Pet Project and Startup Developers: Want to launch immediately in 10 languages? With Goman, it takes as much time as for one.
• 👩‍💼 Teams: A single source of truth for all texts. The developer doesn't wait for the translator, the translator doesn't break the JSON.

---

MCP: Automation of localization in IDE

This is the main feature. MCP (Model Context Protocol) allows you to connect Goman directly to your Copilot or Cursor.

How does it look in practice? Instead of opening 5 files (en.json, de.json, es.json...), searching for the right key, and inserting text, you write in the IDE chat:

"Scan the open file and create translations for all text strings."

Or even for a whole module:

"Localize all components in the src/features/auth folder. Save keys in the auth namespace."

You can ask to localize the entire project at once, but for better control, it is recommended to do it in parts.

What happens under the hood:

1. The agent checks if such a key exists (to avoid duplicates).
2. Generates translations into all languages supported by the project.
3. Saves them to the database.
4. You can immediately use t('actions.save') in the code.

It is important to note: besides the translations themselves, the system stores context for each key (this works both via MCP and via the Editor). Thus, the agent and you can always know where a specific localization is used and what it means.

This saves hours of routine work and allows you to focus on application logic, not dictionaries.

Full Set of Tools (MCP Tools)

The MCP server gives your agent full control over the localization process. The service covers the entire lifecycle of working with texts:

1. Project Discovery (Discovery)

• get_active_languages: The first thing the agent does is check which languages are active in the project. This guarantees that translations will be created only for the required locales.
• get_namespaces: Shows the project structure (list of files/namespaces) so the agent knows exactly where to save new texts (e.g., in common or auth).

2. Search & Verification

• search_localizations: Powerful search by keys and values. The agent can find all buttons with the word "Cancel" or check how the word "Save" is translated elsewhere to maintain consistency.
• get_localization_exists: Precise check of a specific key. Allows avoiding duplication and overwriting of existing important texts.

3. Content Management (Management)

• create_localization: The main tool. Creates or updates translations. Understands context and can add translations immediately to all active project languages in one request.
• delete_localization: Allows deleting obsolete or erroneous keys, maintaining cleanliness in the project.

This set of tools turns your AI agent into a full-fledged localization manager.

Ready-made Templates (Prompts) for a Quick Start

To avoid wasting time writing instructions for AI, the system already has a set of proven prompts for typical tasks. They are available exclusively via MCP and are ready for use by your agent:

• init-project: Full localization setup from scratch. Helps choose the project structure, scans files, and creates the first keys.
• localize-component: Just insert the component code (React, Vue, etc.), and the agent will find all texts, create keys, and even show how to change the code.
• localize-folder: The same, but for entire folders. Ideal for mass localization.
• add-language: Want to add Polish? This prompt will take all existing English keys and translate them into the new language.
• check-coverage: Project audit. Shows which keys are missing in which languages (e.g., "5 translations missing in ru").
• localization-audit: Deep analysis. Finds keys that are no longer used in the code and suggests deleting them.

Just choose the necessary template, and the system itself will substitute the optimal settings for a high-quality result.

Context and Prompt Management in IDE

This function links settings in the web interface with the developer's working environment. The system provides a Prompt Editor, which allows creating specialized instructions for AI agents.

This solves the "blank slate" problem when the model needs the context of the task explained every time.

What the editor allows you to do: The main function is the creation and editing of the prompts themselves. It is through them that you manage the context in your IDE or agent. You write the rules of the game once, and the agent starts following them.

It is important to note: this works not only for translations. You can create prompts for any development tasks — from refactoring to writing tests.

Usage examples:

• For coding: "Use arrow functions, avoid any, write comments in JSDoc format, and always cover new code with tests."
• For interface: You can set a strict rule: "Translate as briefly as possible so the text fits into buttons, use Apple HIG terminology."
• For marketing: "Write emotionally, address the user as 'you', add appropriate emojis."
• For technical documentation: "Maintain an official style, do not translate specific terms (e.g., 'middleware', 'token'), formulate thoughts precisely and dryly."

The user simply selects the necessary prompt from the list in Copilot or Cursor, and the agent instantly switches to the required mode of operation.

---

Editor: Full Control Over Quality

If MCP is speed, then the web editor is precision.

Here you can:

• See the full picture: All languages side by side.
• Edit context: Add a description for AI so it understands that "Home" is a page, not a building.
• Fix nuances: If AI slightly missed the style, you can quickly fix it manually or ask to redo the variant.

This is ideal for marketing texts, landing pages, and important messages where every word matters.

Prompts: Your Personal Style

Why do AI translations sometimes look "machine-like"? Because the model doesn't know your context. In Goman.live, you create Prompts — a set of rules for your project.

This is a replacement for outdated "glossaries". You can tell the model:

• "Address the user as 'you'"
• "Do not translate the brand name 'SuperApp'"
• "Use a cheerful, informal tone"

AI Assistant for Prompts

Don't know how to write a prompt correctly? The built-in AI chat will help formulate ideal instructions for the model so the result is exactly as you expect.

Prompt Storage and Versioning

You can store up to four (currently four) versions of a single prompt and switch between them in one click.
This is very convenient if you want to experiment with formulations or translation rules. Prompt versioning, when used properly, can significantly reduce token consumption. It can also be useful when testing and searching for the most suitable prompts - a prompt testing system has been added to the service - you can immediately run requests for execution and get results.

Collaboration

If you are not working alone - just add a colleague's email.
They will get access to your project, and you can work together on localizations and translations. Restrictions are only by tariff plan. Tokens for translation are taken from the owner's account - that is, the one who "shared".

---

Supported Languages

There is no full list of languages in the service - and that's good.
Models are used that can work with dozens and hundreds of languages, so there are effectively no restrictions.
Translation quality depends on the text itself, the prevalence of the language, and whether there are similar translations in your database.

Translations via the editor often turn out better than via standard tools because context and previous results are taken into account.
And if you work via MCP, the quality depends on the model your agent uses - for example, Claude, GPT, etc.

---

Quality Control: Trust, but Verify

AI is a powerful tool but not perfect. Therefore, Goman.live has built-in insurance mechanisms:

1. Automatic Syntax Check: The service watches so AI doesn't break variables (e.g., {{name}}) or HTML tags.
2. Highlighting Suspicious Places: In the editor, you will see warnings if the translation looks uncertain.

You always have the last word. The service proposes — you approve.

---

Limitations and Features

Since the service runs on LLMs, it has its own features.
First of all - this is the context size: the model can process only a certain amount of information at a time (on average about 8–10 thousand tokens).
If the text is too large, it is better to divide it into logical parts - this way the model better understands the structure and context, and translations come out more accurate.

When using RAG, the context may also be incomplete because separate pieces of text are stored in it and search occurs through it.
Therefore, it is better to translate in small blocks and avoid overloading the model.

This is not a disadvantage, but rather a feature of LLM operation; they simply must "understand" the text within their context window.
But this allows achieving stable results and easily processing translations.

---

About Tokens and Cost

The principle of operation is honesty.

• Via MCP: You use your own API key (Copilot, Cursor, OpenAI), so Goman.live does not charge any additional fees for tokens. It is effectively free from the service side.
• Via Editor: The service's capacities are used, so internal tokens are deducted.

How to get a discount?

A referral program is active: bring a friend and get up to 90% discount. You can contact goman.live.service@gmail.com if you want to learn more.

---

About Data Retention

All your data is stored on our own servers.
A dump is made every 6 hours, and information is not transferred to third parties except for models (LLMs) that process translations. Data after application deletion may be stored for some time - done for the possibility of restoring them upon personal request. You can also export localizations in the form offered in the service at any time. Uploading data is possible via MCP, via a form (one record at a time), or immediately many from a file in the required format.

---

About Cooperation

The project team is open to new ideas and cooperation.
If you have a service or business that can be integrated with Goman.live, or if there is interest in the project — you can contact the developers.
Creation of custom plans, API integrations, and even separate solutions for specific needs is possible.

---

Additional Functionality

Goman.live is not just localizations.
The service allows testing prompts, viewing results, saving them in different versions, and even working in a team. This is described in more detail in the service documentation

---

What's Next

Work is underway on the following things:

• improving prompt integration with GitHub Copilot, Cursor, and other IDEs,
• choice of translation model and use of own API keys,
• improving RAG and automatic update of localizations,
• and many more ideas that will make working with translations even more convenient.

---

Summary: Why is it worth trying?

If you want to create global products but don't want to waste your life on spreadsheets with translations — Goman.live is for you.

1. Speed: Localization becomes part of writing code, not a separate stage.
2. Quality: AI knows context and style better than Google Translate.
3. Convenience: Manage everything right from your favorite IDE.

👉 Try it yourself at goman.live and feel the difference. Your users will say "Thank you" (in their native language 😉).

Vibe Coding Without Pain: A Complete Practical Guide from Real Experience

Vibe coding isn't "magic in a vacuum," but a conscious technique of rapid development with a reliable framework. Over the past months, I've transitioned from Bolt.New to Copilot, Claude, Cursor, and Google AI Studio: over a thousand prompts, dozens of iterations, and many lessons. Below is not a collection of platitudes but a polished set of principles, tools, and templates that truly save time, money, and nerves as the codebase grows.

Introduction: What is Vibe-Coding and How Not to Burn Out

The idea is simple: we move in small but precise steps, committing results to Git, asking AI to make local "diff-only" patches instead of rewriting the world, and maintaining a design system from the very first lines. Instead of "an agent that does everything for you," pair with a wise assistant to whom you clearly formulate the task and boundaries. This way, we avoid "hallucinations," unnecessary restructuring, and do not lose control over tokens.

1) Planning and Mini-Contract: How Not to Get Lost in the First 30 Minutes

Before any coding, create a brief but concrete plan:

• 1–2 sentences about what we are doing: "The user does X and gets Y" (example: "Creates and shares task lists in 30 seconds without registration"). - 3 to 7 main flows/screens - without excessive detail.
• Framework in terms of files: "routes -> modules -> reusable components."
• Blacklist items: "do not reinvent the wheel" such as buttons, inputs, alerts, helpers, validation schemas.

Then, a feature mini-contract: inputs, outputs, errors, constraints, criteria for completion. Afterwards, all prompts are within the scope of this contract.

2) Design System and Consistency: The Framework for the Project

The most costly mistake is starting "on a vibe" without a grid and basic typography. To avoid turning refactoring into manual alignment of margins:

• One base file: breakpoints, spacing scale, grid, typography.
• Main components right away: Button, Input, Select, Alert, Loader, Empty/Error states.
• Check after each iteration: ensure sizes and fonts haven't "spread out."
• In prompts: "Use existing ButtonX, InputY." New styles should not be introduced unnecessarily.

Resource for starting and inspiration: 21st.dev - ready-made UI patterns with prompts.

3) A Stack that Helps, Not Hinders

The broader the community and documentation, the more accurately AI hits the API and patterns. Practical combinations:

• Next.js - frontend + lightweight API layer.
• Tailwind CSS - fast, consistent styles without "CSS-mess" at the start.
• Fastify + MongoDB or Supabase - minimal rituals, many ready-made recipes.

The main thing is not exotic, but reliable model answers.

4) Git Discipline: "Freeze Time" More Often

Your best insurance policy:

• One feature per branch.
• Small work chunks - frequent commits with clear messages.
• Before risky generations/reorganizations - commit or branch.

This way, you won't have to "roll back" 700 lines if the AI "optimized" in the wrong place.

5) Breaking Down the Complex: Spec -> Skeleton -> Flesh -> Harden

Not "do the whole module," but a sequential assembly line:

1. Routes and file skeletons. 2. Basic markup and components.

3. Logic, validation, states.
4. Tests, security, optimization.

AI works more stably when the task boundaries are narrow and clear.

6. Prompts without "magic" and with protective boundaries

The final formulation is your control lever. The minimal template:

"Refactor ProfileForm.tsx: move validation to a separate hook, do not touch the API, preserve prop names and public API, use InputX and ButtonY." The protective phrase "Do not change anything that was not requested" is mandatory.

7) Context and "Reset": When to Open a New Chat

A large chat = drift of patterns, loss of context. Restarting is not a failure, but a form of hygiene:

• Brief introduction for a new window: "Feature X, files A/B/C, only allowed to touch …"
• Remember: too much context is as harmful as too little - leave only the essential.

8) Token Economy: Be cautious with the budget

• Small patches instead of giant "rewrites."
• Diff-first: "Show the patch plan + diff, then apply."
• Model switching: simple - Auto/smaller model; reviews and security - Gemini 2.5 Pro / Sonnet.

9) Engineering Hygiene: Tests, Logs, Types

• Small, clean functions without "lazy" side effects.
• Use ESLint with autofixes; remove dead code at every step.
• Minimum unit tests: "happy path" and edge cases (null/empty/unknown type).
• TypeScript with strict rules - fewer comments, more guarantees.

Before committing: remove unnecessary logs and "temporary" comments - they consume attention during iterations and use up tokens.

10) Security: A Brief but Serious Checklist

• Secrets and keys should only be stored on the server (use environment variables, .gitignore, and ensure they are not exposed to the client).
• Validate and sanitize inputs on the server, and ensure output is properly escaped.
• Permissions should not rely solely on login: each action and resource must undergo permission checks.
• Errors: provide a general message for the user and maintain a detailed log for the developer.
• IDOR and resource ownership: ensure the user has the right to access the specific ID. - DB rules (RLS and analogs) are better at the database level when appropriate.
• Rate limiting and encryption (HTTPS, data "at rest").

11) Iterative Review with a "Big Head" (Google AI Studio / Gemini 2.5 Pro)

When deep inspection is needed:

• Brief overview: "The module does X for Y; main logic in functions..."
• Goals: security, performance, duplicates, unnecessary dependencies.
• Boundaries: "No global restructuring; suggest local patches/steps."

Response Format that Works:

1. Issue;
2. Why it is an issue;
3. Risk;
4. Specific patch/steps.

Then proceed with local diff patches, small tests, and a review.

---

12) "Embedded" Errors: Procedure Without Panic

If, after 2-3 attempts, things are still "off":

1. Ask the model to name the top suspects in the dependency chain.
2. Add logs to narrow spots, add facts (stack, payload, boundaries).
3. If necessary, rollback to a "green" commit and take small steps forward.

13) The Rule "Don't Touch Unless Asked" - and Why I Always Repeat It

AI loves to "tidy up" when it sees an opportunity. Protection - the concluding phrase in each prompt: "Don't change anything beyond the listed." After several iterations, the model begins to respect boundaries.

14) "Common AI Mistakes" File and "Instructions" as Code

• Maintain ai_common_mistakes.md: AI likes to move validation to UI, change prop names, and delete necessary imports - all of this goes here. - Folder instructions/ with markdown examples, prompt templates, "Cursor Rules," and short best practices.
• In the new feature, add a link to the file of mistakes - saves tokens and time.

15) Tools and Patterns That Accelerate Without Fuss

Tools:

• Storybook - isolated UI and documentation of patterns.
• Playwright / Vitest - fast E2E/unit tests; work well with diff patches.
• CodeSandbox / StackBlitz - instant sandboxes for PoC. - Sourcegraph Cody: deep search and contextual patches.
• Continue / Aider / Windsurf / Codeium: lightweight assistants for "getting stuck."
• Tabby / local LLM: affordable generation for template code.
• Perplexity / Phind: quick technical research and approach comparison.
• MCP (Model Context Protocol): standardized access to files/commands without "chatter" in the prompt.
• Commit message generators (see also CommitGPT): save time, but read before pushing. - ESLint with autofix: "entry-level" machine hygiene.

Work Patterns:

• Triple Pass Review: structure -> logic/data flow -> edge cases/security.
• Interface Freeze: lock the public API/props before deep generations.
• Context Ledger: short notes on features (files, solutions, outstanding TODOs) - easily transferable to a new chat.
• Session Reset Cadence: regular reset of long sessions.
• Red Team Self-Check: separate pass for injections, IDOR, races.

16) About Cursor Rules, Instructions, and "Not Being Afraid to Go Back"

• Cursor Rules: An excellent starting point; fix the stack, patterns, prohibitions, and anti-patterns.
• A folder with instructions: examples of components, short recipes for typical tasks (replacing the "hot memory" of the chat).
• If the model goes astray: go back one step, clarify the prompt and context—continuing "by inertia" is more costly.

17) Preventing Undesirable Changes from AI - Politely but Firmly

Be persistent in every request: "Do not add, delete, or rename anything that was not requested." This significantly reduces the "optimization reflex." Vulgar language is unnecessary - clear boundaries work better.

18) Mini-checklist before Commit

• The function fits into existing patterns and components.
• Types are strict, without any; basic tests and logs are present.
• Security: Secrets are on the server; permissions and validation are checked. - UI is consistent: spacing, states, names.
• Commit message is short and informative.

Useful External Resources

Below are external, public sources (services and tools) that provide practical value in the "vibe" approach.

bolt.new
What: An online environment for quickly creating a framework (Full-stack/frontend) with initial code generation through AI.
Why: Instant MVP/prototype before investing in the structure of the main repository. When: In the phase of idea validation or searching for a general form without detailed architecture.

GitHub Copilot
What: A tool for autocomplete and inline suggestions in the editor (VS Code, JetBrains).
Why: To speed up template code (configurations, helper functions, small React components) and reduce the amount of manual typing.
When: When a quick "sketch" or line completion is needed, rather than deep multi-file logic generation. What: Models with strong contextual understanding and cautious outputs. Why: Review of large code blocks, suggestions on structure, security, and style. When: Before refactoring, to find duplications or potential vulnerabilities.

Cursor What: IDE (fork of VS Code) with deep integration of LLM (chat + patch generation + "Rules"). Why: Managed prompts, local diff-patches, quick iterations without manual copying.
When: In main development, when many small structural changes are needed.

cursor.directory
What: A catalog of ready-made Cursor Rules and prompt templates.
Why: A starter set of rules (style, architecture, protective constraints) instead of manual development.
When: At the stage of setting up "rules of the game" in the project. Google AI Studio (Gemini 2.5 Pro)
What: An interface to models with a large context window.
Why: Comprehensive checks - security, performance, duplications, dependencies; summarization before restructuring.
When: When the codebase is already significant, and a "strategic overview" is needed.

21st.dev
What: A collection of UI patterns with example prompts.
Why: To unify styles and component structures without inventing "from scratch." When: before scaling the frontend or standardizing forms/lists.

Sourcegraph Cody
What: Intelligent search across large repositories and patch generation.
Why: To find all function usages/dependencies and build a picture of connections before making changes.
When: before deep refactoring or module removal.

CodeSandbox
What: Cloud sandboxes for instant application launch without local installation. Why: To test a library, evaluate an idea, or demonstrate a concept to a colleague.
When: Early validation or isolated demonstration.

Storybook
What: An isolated environment for viewing and testing UI components.
Why: To ensure the consistency of the design system and visually check states (loading/empty/error).
When: During the extraction of common components or before scaling the front end. Playwright
What: A tool for E2E tests (browser scenarios with high accuracy).
Why: To check key user flows after automatic patches by AI.
When: Before merging important changes or releasing a version.

Vitest
What: A fast unit/integration tester for the Vite ecosystem/modern TS.
Why: To cover pure functions and hooks to stabilize refactoring. When: Right after extracting small utilities or logic into separate modules.

Perplexity
What: LLM search engines with summarized answers and links.
Why: Instantly learn API nuances, library statuses, and compare approaches.
When: Before choosing a stack or optimization.

LangSmith
What: Tools for assessing the quality of LLM integrations and prompts.
Why: Objectively evaluate if the result improves with your rules or corrections. When: when the number of prompts and models is greater than 1, and quality management is required.

Regex101
What: An online debugger for regular expressions with explanations.
Why: To quickly verify and correctly construct validation/parsing rules.
When: Before implementing complex validation in a form/API.

How to effectively combine:

1. Idea -> bolt.new (prototype) -> transfer to Cursor.
2. Structure -> Sourcegraph (dependencies) -> Claude (comments) -> local patches.

UI

• 21st.dev (pattern) + Storybook (review) + Tailwind (styles).

Security

• OWASP (checklist) + Gemini (audit) + Playwright (flows).

Cleanliness

• ESLint (rules) + TypeScript (strict types) + Vitest (tests).

Gradually introduce resources—not all at once: this reduces cognitive load and increases process stability.

Conclusion: Speed with a Framework.

Vibe coding is not chaos or an "end in itself." It is a cycle of "vision -> small step -> check -> stabilization." The better the vision and patterns, the more AI becomes a partner rather than a source of surprises and problems. Mistakes will occur, but with this set, you won't get lost—just continue to iterate without pain.

Thank You for Your Attention

Thank you for reading. I hope the material will be useful to you. If you liked it, please support our project.

P.S.: The image in the header is intentionally a bit quirky.

Hi there!

I've been meaning to write this article for more than a month now, but there hasn't been time or the right mood. Still, I gathered my thoughts and finally cobbled together something. I hope you find it useful. Take a look at GitHub — there are ready-to-run working examples that you can launch. For a better understanding of what's happening, get acquainted with the structure and code of the MCP server.

Today we connect Cursor and VS Code to your APIs via MCP.

Sometimes you look at your own useful scripts and think: 'How can you neatly connect them to AI without unnecessary hassle? What do you need for this? From which side should you approach?' Today, in this article, we will try to solve this problem and learn how to create your own MCPs. And you can also check my previous AI articles.

---

MCP in a nutshell

MCP (Model Context Protocol) is a unified 'translator' between your tools and intelligent clients (chat assistants; for example, agents in Cursor). Instead of another fragmented API, you precisely describe what your tool can do and what its inputs/outputs are — then everything works according to the standard.

Why is MCP convenient?

The main idea of MCP is that your API can be connected to the model as a separate agent with transparent rules:

• Standardization. A single language for tools and clients instead of a set of different protocols.
• Governance. Tools connected to the model have explicit schemas, predictable behavior, clear rights.
• Fast integration. Connect API/FS/DB/DevOps processes — and use them from the IDE or the chat.

Where MCP is particularly relevant

MCP is suitable for a range of tasks, most of which relate to development (now primarily editors adapted to work with external tools via MCP). For example:

• DevTools and ChatOps: CI/CD commands, diagnostics, and access to logs.
• Data/BI: aggregated queries, insightful summaries.
• Internal APIs: a single control point for the team.
• RAG/automation: data collection and pre- and post-processing.
• Working with documentation (for example, Confluence) and others. List of proposed MCPs for VS Code: GitHub

---

How to build a simple MCP server with HTTP transport (Bun/Node)

Back to building our server. I have already prepared several examples of tools in the training repository; you can explore them at the link lesson8_mcp/mcp_server in the bel_geek repository. Code compatible with Bun and Node.js.

What we'll build

We'll create a simple server without unnecessary bells and whistles. This will be a local HTTP server with /healthz and /mcp, stateless, with three demo tools (the same set as in the repository) to immediately test MCP:

• Routes:
  • GET /healthz - health check.
  • /mcp - MCP endpoint (GET, POST, DELETE).
• Stateless mode (no sessions).
• Three tools:
  • echo - returns the transmitted text. - get_proverb_by_topic — proverbs by topic (topic, random, limit)
  • get_weather — local weather from wttr.in.

---

---

🚀 Setting up the server and connecting it to Cursor/VS Code

The theory is done; time to act: clone, install, run — and MCP is up and running.

🔑 Prerequisites (what you need before starting)

No surprises here:

• Node.js ≥ 18 or Bun ≥ 1.x (Bun starts faster — fewer unnecessary moves). - Two packages: @modelcontextprotocol/sdk (the MCP foundation) and zod (to describe input parameters precisely and reliably).
• Docker — only if you want to package everything into a container right away. For local testing, it's not required.

⚡️ Running an example

No unnecessary philosophy—simply clone the repository and run:

textCopy
1git clone https://github.com/bel-frontend/RAG
2cd RAG/lesson8_mcp/mcp_server

textCopy
1bun install
2bun index.ts

If everything goes well, the console will display the message:

textCopy
1MCP Streamable HTTP Server on http://localhost:3002/mcp
2Available endpoints: /healthz, /mcp

🎉 Server! It's alive! Let's check its heartbeat:

textCopy
1curl -s http://localhost:3002/healthz

The response should be in the format { ok: true, timestamp: ... }.

🧩 Architecture in simple terms

How the server works:

1. An MCP server is created — it registers tools (echo, get_proverb_by_topic, get_weather).
2. An HTTP transport is added — MCP can receive and send requests via /mcp.
3. Routes:

• /healthz — returns a simple JSON object to verify that the server is alive.
• /mcp - the main endpoint through which Cursor or VS Code connects to the tools.

4. Context — the headers (apikey, applicationid) are stored in storage so that the tools can use them.
5. Termination — on shutdown (SIGINT/SIGTERM) the server closes properly.

Key Implementation Details

The server architecture consists of three main components:

1. MCP Server & Transport

typescriptCopy
1const mcp = new McpServer({ name: 'test-mcp', version: '0.1.0' });
2const transport = new StreamableHTTPServerTransport({
3    sessionIdGenerator: undefined  // Stateless mode
4});
5mcp.connect(transport);

2. HTTP Routing

Two endpoints handle all traffic:

• /healthz - health checks
• /mcp - MCP protocol communication (POST for tool calls, GET/DELETE for sessions)

3. CORS & Error Handling

The server includes proper CORS headers and graceful shutdown on SIGINT/SIGTERM signals.

🛠 Tools — the main magic here

Three simple tools demonstrate MCP capabilities:

1. Echo Tool - Returns input text (useful for testing)

typescriptCopy
1mcp.registerTool('echo', {
2    title: 'Echo',
3    description: 'Return the same text',
4    inputSchema: { text: z.string() }
5}, async ({ text }) => ({
6    content: [{ type: 'text', text }]
7}));

2. Proverbs Tool - Fetches Belarusian proverbs with filtering

typescriptCopy
1mcp.registerTool('get_proverb_by_topic', {
2    inputSchema: {
3        topic: z.string().optional(),
4        random: z.boolean().optional(),
5        limit: z.number().int().positive().max(200).optional()
6    }
7}, async ({ topic, random, limit }) => {
8    const data = await fetch(PROVERBS_URL).then(r => r.json());
9    let items = data.map(d => d.message);
10    
11    // Filter by topic
12    if (topic) {
13        items = items.filter(m => m.toLowerCase().includes(topic.toLowerCase()));
14    }
15    
16    // Random selection with Fisher-Yates shuffle
17    if (random) {
18        // ... shuffle logic
19    }
20    
21    return { content: [{ type: 'text', text: items.join('\n') }] };
22});

3. Weather Tool - Shows current weather via wttr.in

typescriptCopy
1mcp.registerTool('get_weather', {
2    inputSchema: { city: z.string() }
3}, async ({ city }) => {
4    const weather = await fetch(`https://wttr.in/${city}?format=3`).then(r => r.text());
5    return { content: [{ type: 'text', text: weather }] };
6});

Key Points:

• Use Zod schemas for input validation
• Return format: { content: [{ type: 'text', text: string }] }
• Handle errors gracefully with try-catch
• Add timeout handling for external APIs

🖇 Connecting to Cursor and VS Code

And now the most interesting part — integration. When MCP is running, we can use it through Cursor or GitHub Copilot in VS Code.

Cursor:

1. Start the server (bun index.ts).
2. Create the file in the project at ./.cursor/mcp.json with the following configuration:

jsonCopy
1{
2  "mcpServers": {
3    "test-mcp": {
4      "type": "http",
5      "url": "http://localhost:3002/mcp",
6      "headers": {
7        "apiKey": "API_KEY_1234567890",
8        "applicationId": "APPLICATION_ID"
9      }
10    }
11  }
12}

Open Settings → Model Context Protocol and make sure that test-mcp is in the list. In the Cursor chat, type (make sure that the agent is enabled): "Invoke the get_weather tool for Minsk" - and see the response.

VS Code (Copilot Chat)

Here it's almost the same, only the file needs to be placed into .vscode/mcp.json. After that, in the Copilot Chat toolbar your tool should appear.

jsonCopy
1{
2    "servers": {
3        "test-mcp": {
4            "type": "http",
5            "url": "http://localhost:3002/mcp",
6            "headers": {
7                "apiKey": "API_KEY_1234567890",
8                "applicationId": "APPLICATION_ID"
9            }
10        }
11    }
12}

Pro tip: You can configure multiple MCP servers or use environment variables for credentials.

🐳 Docker Deployment - Production Ready

Quick Start:

Would you like to package it right away? Build and run it in Docker:

bashCopy
1docker compose build --no-cache
2docker compose up -d

MCP will be available at http://localhost:3002/mcp.

Understanding the Docker Setup

The repository includes a complete Docker configuration:

Dockerfile Example:

dockerfileCopy
1FROM oven/bun:1 as base
2WORKDIR /app
3
4COPY package.json bun.lockb ./
5RUN bun install --frozen-lockfile --production
6
7COPY . .
8
9EXPOSE 3002
10
11HEALTHCHECK --interval=30s --timeout=3s CMD \
12  curl -f http://localhost:3002/healthz || exit 1
13
14CMD ["bun", "index.ts"]

docker-compose.yml:

yamlCopy
1version: '3.8'
2
3services:
4  mcp-server:
5    build: .
6    container_name: mcp-server
7    ports:
8      - "3002:3002"
9    environment:
10      - NODE_ENV=production
11    restart: unless-stopped

Useful Docker Commands:

bashCopy
1# View logs
2docker compose logs -f mcp-server
3
4# Restart service
5docker compose restart
6
7# Stop and remove
8docker compose down
9
10# Rebuild and restart
11docker compose up -d --build

Team-friendly collaboration: everyone uses the same mental model and doesn't waste time on "what works for me—doesn't work for you."

🤔 Typical pitfalls and how to bypass them

• CORS—when connecting from a browser, you must allow headers. We added a basic variant in the code.
• Stateless/Stateful — in the example the server is stateless. If you need sessions, enable sessionIdGenerator.
• API headers—in Node.js they arrive in lowercase (apikey), not apiKey. It’s easy to get confused. External services (proverbs and weather) can slow things down. Add timeouts and caching.

✍️ How to build your own tool

Here is a simple example:

jsCopy
1import { z } from 'zod';
2import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
3
4export function registerMyTools(mcp: McpServer) {
5  mcp.registerTool(
6    'my_tool',
7    {
8      title: 'my_tool',
9      description: 'A simple tool that adds 2+2',
10      inputSchema: { name: z.string() },
11    },
12    async ({ name }) => ({
13      content: [{ type: 'text', text: `Hello, ${name}!` }],
14    })
15  );
16}

Ready—now you can add your own 'tricks' to MCP and use them from the IDE.

✍️ Building Custom Tools

Here's a practical example of a database query tool:

typescriptCopy
1import { z } from 'zod';
2import { Pool } from 'pg';
3
4const pool = new Pool({ /* config */ });
5
6export function registerDatabaseTools(mcp: McpServer) {
7    mcp.registerTool('query_users', {
8        description: 'Search users by name or email',
9        inputSchema: {
10            searchTerm: z.string().min(2),
11            limit: z.number().int().max(100).default(10)
12        }
13    }, async ({ searchTerm, limit }) => {
14        const result = await pool.query(
15            'SELECT id, name, email FROM users WHERE name ILIKE $1 LIMIT $2',
16            [`%${searchTerm}%`, limit]
17        );
18        
19        return {
20            content: [{
21                type: 'text',
22                text: result.rows.map(r => `${r.name} <${r.email}>`).join('\n')
23            }]
24        };
25    });
26}

Best Practices:

• Always validate inputs with Zod
• Use parameterized queries to prevent SQL injection
• Handle errors gracefully and return useful messages
• Add timeouts for external API calls
• Keep tool descriptions clear and concise

🎯 Results

We built an MCP server on Bun/Node, added three demo tools, connected it to Cursor and VS Code, ran it in Docker and discussed typical issues. The main thing is that MCP makes connecting your own tools to smart IDEs simple and standardized.

The future lies only in your imagination: you can integrate DevOps processes, databases, BI queries, and internal APIs. MCP makes it possible for other team members to simply pick it up and use it.

What's next

We built a simple MCP server with HTTP transport, added three practical tools, configured CORS, and demonstrated configurations for Cursor and GitHub Copilot (VS Code), as well as a Docker deployment. The next steps are to extend the toolset, implement authentication, and add logging and caching. If needed, stateful sessions and a production deployment. If this resonates with you, create your own tools and share them with the community! Will create smart and useful things.

Greetings! Today, I’m sharing a short guide on how to set up a project to work with GitHub Copilot.

Reliable AI workflow with GitHub Copilot: complete guide with examples (2025)

This guide shows how to build predictable and repeatable AI processes (workflows) in your repository and IDE/CLI using agentic primitives and context engineering. Here you will find the file structure, ready-made templates, security rules, and commands.

⚠️ Note: the functionality of prompt files and agent mode in IDE/CLI may change - adapt the guide to the specific versions of Copilot and VS Code you use.

---

1) Overview: what the workflow consists of

The main goal is to break the agent's work into transparent steps and make them controllable. For this there are the following tools:

• Custom Instructions (.github/copilot-instructions.md) - global project rules (how to build, how to test, code style, PR policies).
• Path-specific Instructions (.github/instructions/*.instructions.md) - domain rules targeted via applyTo (glob patterns).
• Chat Modes (.github/chatmodes/*.chatmode.md) - specialized chat modes (for example, Plan/Frontend/DBA) with fixed tools and model.
• Prompt Files (.github/prompts/*.prompt.md) - reusable scenarios/"programs" for typical tasks (reviews, refactoring, generation).
• Context helpers (docs/*.spec.md, docs/*.context.md, docs/*.memory.md) - specifications, references, and project memory for precise context.
• MCP servers (.vscode/mcp.json or via UI) - tools and external resources the agent can use.

---

2) Project file structure

The following structure corresponds to the tools described above and helps to compose a full workflow for agents.

textCopy
1.github/
2  copilot-instructions.md
3  instructions/
4    backend.instructions.md
5    frontend.instructions.md
6    actions.instructions.md
7  prompts/
8    implement-from-spec.prompt.md
9    security-review.prompt.md
10    refactor-slice.prompt.md
11    test-gen.prompt.md
12  chatmodes/
13    plan.chatmode.md
14    frontend.chatmode.md
15.vscode/
16  mcp.json
17docs/
18  feature.spec.md
19  project.context.md
20  project.memory.md

---

3) Files and their purpose - technical explanation

Now let's review each tool separately and its role. Below is how it’s arranged under the hood: what these files are, why they exist, how they affect the agent's understanding of the task, and in what order they are merged/overridden. The code examples below match the specification.

File/folder	What it is	Why	Where it applies
.github/copilot-instructions.md	Global project rules	Consistent standards for all responses	Entire repository
.github/instructions/*.instructions.md	Targeted instructions for specific paths	Different rules for frontend/backend/CI	Only for files matching the applyTo
.github/chatmodes/*.chatmode.md	A set of rules + allowed tools for a chat mode	Separate work phases (plan/refactor/DBA)	When that chat mode is selected
.github/prompts/*.prompt.md	Task "scenarios" (workflow)	Re-run typical processes	When invoked via /name or CLI
docs/*.spec.md	Specifications	Precise problem statements	When you @-mention them in dialogue
docs/*.context.md	Stable references	Reduce "noise" in chats	By link/@-mention
docs/*.memory.md	Project memory	Record decisions to avoid repeats	By link/@-mention
.vscode/mcp.json	MCP servers configuration	Access to GitHub/other tools	For this workspace

Merge order of rules and settings: Prompt frontmatter → Chat mode → Repo/Path instructions → Defaults.

---

And now let's review each tool separately.

3.1. Global rules - .github/copilot-instructions.md

What it is: A Markdown file with short, verifiable rules: how to build, how to test, code style, and PR policies.

Why: So that all responses rely on a single set of standards (no duplication in each prompt).

How it works: The file automatically becomes part of the system context for all questions within the repository. No applyTo (more on that later) - it applies everywhere.

Minimal example:

mdCopy
1# Repository coding standards
2- Build: `npm ci && npm run build`
3- Tests: `npm run test` (coverage ≥ 80%)
4- Lint/Typecheck: `npm run lint && npm run typecheck`
5- Commits: Conventional Commits; keep PRs small and focused
6- Docs: update `CHANGELOG.md` in every release PR

Tips.

1. Keep points short.
2. Avoid generic phrases.
3. Include only what can affect the outcome (build/test/lint/type/PR policy).

---

3.2. Path-specific instructions - .github/instructions/*.instructions.md

What it is: Modular rules with YAML frontmatter applyTo - glob patterns of files for which they are included.

Why: To differentiate standards for different areas (frontend/backend/CI). Allows controlling context based on the type of task.

How it works: When processing a task, Copilot finds all *.instructions.md whose applyTo matches the current context (files you are discussing/editing). Matching rules are added to the global ones.

Example:

mdCopy
1---
2applyTo: "apps/web/**/*.{ts,tsx},packages/ui/**/*.{ts,tsx}"
3---
4- React: function components and hooks
5- State: Zustand; data fetching with TanStack Query
6- Styling: Tailwind CSS; avoid inline styles except dynamic cases
7- Testing: Vitest + Testing Library; avoid unstable snapshots

Note.

1. Avoid duplicating existing global rules.
2. Ensure the glob actually targets the intended paths.

---

3.3. Chat modes - .github/chatmodes/*.chatmode.md

What it is: Config files that set the agent’s operational mode for a dialogue: a short description, the model (if needed) and a list of allowed tools.

Why: To separate work phases (planning/frontend/DBA/security) and restrict tools in each phase. This makes outcomes more predictable.

File structure:

mdCopy
1---
2description: "Plan - analyze code/specs and propose a plan; read-only tools"
3model: GPT-4o
4tools:
5  - "search/codebase"
6---
7In this mode:
8- Produce a structured plan with risks and unknowns
9- Do not edit files; output a concise task list instead

How it works:

• The chat mode applies to the current chat in the IDE.
• If you activate a prompt file, its frontmatter takes precedence over the chat mode (it can change the model and narrow tools).
• Effective allowed tools: chat mode tools, limited by prompt tools and CLI --allow/--deny flags.

Management and switching:

• In the IDE (VS Code):

  1. Open the Copilot Chat panel.
  2. In the top bar, choose the desired chat mode from the dropdown (the list is built from .github/chatmodes/*.chatmode.md + built-in modes).
  3. The mode applies only to this thread. To change - select another or create a new thread with the desired mode.
  4. Check the active mode in the header/panel of the conversation; the References will show the *.chatmode.md file.

• In the CLI: (a bit hacky, better via prompts)

  • There is usually no dedicated CLI flag to switch modes; encode desired constraints in the prompt file frontmatter and/or via --allow-tool/--deny-tool flags.
  • You can instruct in the first line: “Use the i18n chat mode.” - if the version supports it, the agent may switch; if not, the prompt frontmatter will still enforce tools.

• Without switching the mode: run a prompt with the required tools: in frontmatter - it will limit tools regardless of chat mode.

Diagnostics: if the agent uses "extra" tools or does not see needed ones - check: (1) which chat mode is selected; (2) tools in the prompt frontmatter; (3) CLI --allow/--deny flags; (4) References in the response (visible *.chatmode.md/*.prompt.md files).

---

3.4. Prompt files - .github/prompts/*.prompt.md

What it is: Scenario files for repeatable tasks. They consist of YAML frontmatter (config) and a body (instructions/steps/acceptance criteria). They are invoked in chat via /name or via CLI.

When to use: When you need a predictable, automatable process: PR review, test generation, implementing a feature from a spec, etc.

Frontmatter structure

• description - short goal of the scenario.
• mode - ask (Q&A, no file edits) · edit (local edits in open files) · agent (multistep process with tools).
• model - desired model profile.
• tools - list of allowed tools for the scenario (limits even what the chat mode allowed).

Execution algorithm (sequence)

1. Where to run:

   • In chat: type /prompt-name and arguments in the message field.
   • In CLI: call copilot and pass the /prompt-name … line (interactive or via heredoc / -p flag).

2. Context collection: Copilot builds the execution context in the following order: repo-instructions → path-instructions (applyTo) → chat mode → frontmatter prompt (the prompt frontmatter has the highest priority and can narrow tools/change the model).

3. Parameter parsing (where and how):

   • In chat: parameters go in the same message after the name, for example: /security-review prNumber=123 target=apps/web.
   • In CLI: parameters go in the same /… line in stdin or after the -p flag.
   • Inside the prompt file they are available as ${input:name}. If a required parameter is missing, the prompt can ask for it textually in the dialog.

4. Resolving tool permissions:

   • Effective allowed tools: chat mode tools, limited by prompt tools and CLI --allow/--deny flags.
   • If a tool is denied, the corresponding step is skipped or requires confirmation/change of policy.

5. Executing steps from the prompt body: the agent strictly follows the Steps order, doing only what is permitted by policies/tools (searching the codebase, generating diffs, running tests, etc.). For potentially risky actions, it requests confirmation.

6. Validation gates: at the end, the prompt runs checks (build/tests/lint/typecheck, output format checks). If a gate fails - the agent returns a list of issues and proposes next steps (without auto-merging/writing changes).

7. Where the result appears (what and where you see it):

   • Main response - in the chat panel (IDE) or in stdout (CLI): tables, lists, textual reports, code blocks with diff.
   • File changes - in your working tree: in IDE you see a diff/suggested patches; in CLI files change locally (if allowed by tools).
   • Additional artifacts - e.g., a PR comment if GitHub tools are allowed and the prompt specifies it.

Output format and checks (recommended)

• Always specify the output format (for example, table "issue | file | line | severity | fix").
• Add validation gates: build/tests/lint/typecheck; require unified-diff for proposed changes; a TODO list for unresolved issues.

Example of a complete prompt file

mdCopy
1---
2mode: 'agent'
3model: GPT-4o
4tools: ['search/codebase']
5description: 'Implement a feature from a spec'
6---
7Goal: Implement the feature described in @docs/feature.spec.md.
8
9Steps:
101) Read @docs/feature.spec.md and produce a short implementation plan (bullets)
112) List files to add/modify with paths
123) Propose code patches as unified diff; ask before installing new deps
134) Generate minimal tests and run them (report results)
14
15Validation gates:
16- Build, tests, lint/typecheck must pass
17- Output includes the final diff and a TODO list for anything deferred
18- If any gate fails, return a remediation plan instead of "done"

Anti-patterns

• Watered-down descriptions: keep description 1–2 lines.
• Missing output format.
• Too many tools: allow only what is needed (tools).

Quick start

• Chat: /implement-from-spec
• CLI: copilot <<<'/implement-from-spec' or copilot -p "Run /implement-from-spec"

---

3.5. Context files - specs/context/memory

What it is: Helper Markdown files (not special types) that you @-mention in dialogue/prompt. Typically stored as documentation.

• docs/*.spec.md - precise problem statements (goal, acceptance, edge cases, non-goals).
• docs/*.context.md - short references (API policies, security, UI styleguide, SLA).
• docs/*.memory.md - "decision log" with dates and reasons so the agent does not return to old disputes.

Example:

mdCopy
1# Feature: Export report to CSV
2Goal: Users can export the filtered table to CSV.
3Acceptance criteria:
4- "Export CSV" button on /reports
5- Server generates file ≤ 5s for 10k rows
6- Column order/headers match UI; locale-independent values
7Edge cases: empty values, large numbers, special characters
8Non-goals: XLSX, multi-column simultaneous filters

---

3.6. MCP - .vscode/mcp.json

What it is: Configuration for Model Context Protocol servers (for example, GitHub MCP) which enable tools for the agent.

Why: So the agent can read PRs/issues, run tests, interact with DB/browser - within allowed permissions.

Example:

jsonCopy
1{
2  "servers": {
3    "github-mcp": {
4      "type": "http",
5      "url": "https://api.githubcopilot.com/mcp"
6    }
7  }
8}

Security. Connect only trusted servers; use allow/deny tool lists in prompts/chat modes/CLI.

---

3.7. General context merge order and priorities (rules & tools)

1. Instructions: copilot-instructions + all *.instructions.md with applyTo that match current paths. A specific instruction is added to the common context.
2. Chat mode: restricts the toolset and (if needed) the model for the session.
3. Prompt frontmatter: has the highest priority; can limit tools and override the model.
4. Context: anything you @-mention is guaranteed to be considered by the model.

Diagnostics. Check the References section in outputs - it shows which instruction files were considered and which prompt was run.

3.8. Example: full i18n cycle with Goman MCP (create/update/prune)

Below is the exact process and templates on how to ensure: (a) when creating UI components localization keys are created/updated in Goman; (b) when removing components - unused entries are detected and (after confirmation) deleted.

Code snippets and frontmatter are in English.

3.8.1. MCP config - connect Goman

/.vscode/mcp.json

jsonCopy
1{
2  "servers": {
3    "goman-mcp": {
4      "type": "http",
5      "url": "https://mcp.goman.live/mcp",
6      "headers": {
7        "apiKey": "<YOUR_API_KEY>",
8        "applicationid": "<YOUR_APPLICATION_ID>"
9      }
10    }
11  }
12}

3.8.2. Repo/Path rules - enforce i18n by default

/.github/instructions/frontend.instructions.md (addition)

mdCopy
1---
2applyTo: "apps/web/**/*.{ts,tsx}"
3---
4- All user-facing strings **must** use i18n keys (no hardcoded text in JSX/TSX)
5- Key naming: `<ui_component_area>.<name>` (e.g., `ui_button_primary.label`)
6- When creating components, run `/i18n-component-scaffold` and commit both code and created keys
7- When deleting components, run `/i18n-prune` and confirm removal of unused keys

3.8.3. Chat mode - limited i18n tools

/.github/chatmodes/i18n.chatmode.md

mdCopy
1---
2description: "i18n - manage localization keys via Goman MCP; enforce no hardcoded strings"
3model: GPT-4o
4tools:
5  - "files"
6  - "goman-mcp:*"
7---
8In this mode, prefer:
9- Creating/updating keys in Goman before writing code
10- Checking for existing keys and reusing them
11- Producing a table of changes (created/updated/skipped)

3.8.4. Prompt - scaffold component + keys in Goman

/.github/prompts/i18n-component-scaffold.prompt.md

mdCopy
1---
2mode: 'agent'
3model: GPT-4o
4tools: ['files','goman-mcp:*']
5description: 'Scaffold a React component with i18n keys synced to Goman'
6---
7Inputs: componentName, namespace (e.g., `ui.button`), path (e.g., `apps/web/src/components`)
8
9Goal: Create a React component and ensure all user-visible strings use i18n keys stored in Goman.
10
11Steps:
121) Plan the component structure and list all user-visible strings
132) For each string, propose a key under `${namespace}`; reuse if it exists
143) Using Goman MCP, create/update translations for languages: en, be, ru (values may be placeholders)
154) Generate the component using `t('<key>')` and export it; add a basic test
165) Output a Markdown table: key | en | be | ru | action(created/updated/reused)
17
18Validation gates:
19- No hardcoded literals in the produced .tsx
20- Confirm Goman actions succeeded (report tool responses)
21- Tests and typecheck pass

Example component code:

tsxCopy
1import { t } from '@/i18n';
2import React from 'react';
3
4type Props = { onClick?: () => void };
5
6export function PrimaryButton({ onClick }: Props) {
7  return (
8    <button aria-label={t('ui.button.primary.aria')} onClick={onClick}>
9      {t('ui.button.primary.label')}
10    </button>
11  );
12}

3.8.5. Prompt - prune unused keys when removing components

/.github/prompts/i18n-prune.prompt.md

mdCopy
1---
2mode: 'agent'
3model: GPT-4o
4tools: ['files','goman-mcp:*']
5description: 'Find and prune unused localization keys in Goman after code deletions'
6---
7Inputs: pathOrDiff (e.g., a deleted component path or a PR number)
8
9Goal: Detect keys that are no longer referenced in the codebase and remove them from Goman after confirmation.
10
11Steps:
121) Compute the set of removed/renamed UI elements (scan git diff or provided paths)
132) Infer candidate keys by namespace (e.g., `ui.<component>.*`) and check code references
143) For keys with **zero** references, ask for confirmation and delete them via Goman MCP
154) Produce a Markdown table: key | status(kept/deleted) | reason | notes
16
17Validation gates:
18- Never delete keys that still have references
19- Require explicit confirmation before deletion
20- Provide a rollback list of deleted keys

3.8.6. Prompt - sync and check missing translations (optional)

/.github/prompts/i18n-sync.prompt.md

mdCopy
1---
2mode: 'agent'
3model: GPT-4o
4tools: ['files','goman-mcp:*']
5description: 'Sync new/changed i18n keys and check for missing translations'
6---
7Goal: Compare code references vs Goman and fill gaps.
8
9Steps:
101) Scan code for `t('...')` keys under provided namespaces
112) For missing keys in Goman - create them (placeholder text ok)
123) For missing languages - create placeholders and report coverage
134) Output coverage table: key | en | be | de | missing

4) How to use this (IDE and CLI)

4.1. In VS Code / other IDE

• Open Copilot Chat - choose Agent/Edit/Ask in the dropdown.
• For prompt files just type /file-name without extension (e.g. /security-review).
• Add context using @-mentions of files and directories.
• Switch chat mode (Plan/Frontend/DBA) when the task changes.

4.2. In Copilot CLI (terminal)

• Example install: npm install -g @github/copilot → run copilot.
• Interactively: “Run /implement-from-spec on @docs/feature.spec.md”.
• Programmatically/in CI: copilot -p "Implement feature from @docs/feature.spec.md" --deny-tool shell("rm*").
• Add/restrict tools with flags: --allow-all-tools, --allow-tool, --deny-tool (global or by pattern, e.g. shell(npm run test:*)).

4.3. Cookbook commands for CLI (chat modes and prompts)

Below are ready recipes. All commands should run from the repository root and respect your deny/allow lists.

A. Run a prompt file in an interactive session

bashCopy
1copilot
2# inside the session (enter the line as-is)
3/security-review prNumber=123

B. Run a prompt file non-interactively (heredoc)

bashCopy
1copilot <<'EOF'
2/security-review prNumber=123
3EOF

C. Pass prompt file parameters

bashCopy
1copilot <<'EOF'
2/implement-from-spec path=@docs/feature.spec.md target=apps/web
3EOF

Inside the prompt you can read values as ${input:target} and ${input:path}.

D. Run a prompt with safe tool permissions

bashCopy
1copilot --allow-tool "shell(npm run test:*)" \
2        --deny-tool  "shell(rm*)" \
3        <<'EOF'
4/security-review prNumber=123
5EOF

E. Use a chat mode (specialized mode) in the CLI

bashCopy
1copilot
2# inside the session - ask to switch to the required mode and run the prompt
3Use the i18n chat mode.
4/i18n-component-scaffold componentName=PrimaryButton namespace=ui.button path=apps/web/src/components

If your client supports selecting the mode via a menu - choose i18n before running the prompt. If not - specify constraints in the prompt frontmatter (tools and rules in the prompt body).

F. Send file links/diffs as context

bashCopy
1copilot <<'EOF'
2Please review these changes:
3@apps/web/src/components/PrimaryButton.tsx
4@docs/feature.spec.md
5/security-review prNumber=123
6EOF

G. Change the model for a specific run

We recommend specifying the model in the prompt frontmatter. If supported, you can also pass a model flag at runtime:

bashCopy
1copilot --model GPT-4o <<'EOF'
2/implement-from-spec
3EOF

H. i18n cycle with Goman MCP (CHAT)

Run sequentially in a chat thread:

textCopy
1/i18n-component-scaffold componentName=PrimaryButton namespace=ui.button path=apps/web/src/components
2/i18n-prune pathOrDiff=@last-diff
3/i18n-sync namespace=ui.button

What you get:

• resulting tables/reports in the chat panel;
• code changes in your working tree (IDE shows diffs);
• no CLI commands for Goman MCP are required here.

---

5) Context engineering: how not to "dump" excess context

1. Split sessions by phases: Plan → Implementation → Review/Tests. Each phase has its own Chat Mode.
2. Attach only necessary instructions: use path-specific *.instructions.md instead of dumping everything.
3. Project memory: record short ADRs in project.memory.md - this reduces agent "forgetting" between tasks.
4. Context helpers: keep frequent references (API/security/UI) in *.context.md and link to them from prompt files.
5. Focus on the task: in prompt files always state the goal, steps and output format (table, diff, checklist).

---

6) Security and tool management

• Require explicit confirmation before running commands/tools. In CI use --deny-tool by default and add local allow lists.
• Permission patterns: allow only what is necessary (shell(npm run test:*), playwright:*), deny dangerous patterns (shell(rm*)).
• Secrets: never put keys in prompts or instructions; use GitHub Environments or local secret managers and .env with .gitignore.
• Any MCP - only from trusted origins; review the code/config before enabling.
• Patch checks: require unified-diff and explanations in prompt files - this makes review easier.

---

7) CI/CD recipe (optional example)

Ensure "everything builds": run Copilot CLI in a dry/safe mode to produce a comment for the PR.

yamlCopy
1# .github/workflows/ai-review.yml
2name: AI Review (Copilot CLI)
3on:
4  pull_request:
5    types: [opened, synchronize, reopened]
6
7jobs:
8  ai_review:
9    runs-on: ubuntu-latest
10    permissions:
11      contents: read
12      pull-requests: write
13    steps:
14      - uses: actions/checkout@v4
15      - uses: actions/setup-node@v4
16        with:
17          node-version: 22
18      - name: Install Copilot CLI
19        run: npm install -g @github/copilot
20      - name: Run security review prompt (no dangerous tools)
21        env:
22          PR: ${{ github.event.pull_request.number }}
23        run: |
24          copilot -p "Run /security-review with prNumber=${PR}" \
25            --deny-tool shell("rm*") --deny-tool shell("curl*") \
26            --allow-tool shell("npm run test:*") \
27            --allow-tool "github:*" \
28            > ai-review.txt || true
29      - name: Comment PR with results
30        if: always()
31        run: |
32          gh pr comment ${{ github.event.pull_request.number }} --body-file ai-review.txt

Tip: keep tight deny/allow lists; do not give the agent "full freedom" in CI.

---

8) Small scenarios and tips that might be useful

• From idea to PR: /plan - discuss the plan - /implement-from-spec → local tests - PR - /security-review.
• Maintenance: /refactor-slice for local improvements without behavior changes.
• Tests: /test-gen for new modules + manual additions for edge cases.
• Gradual rollout: start with 1–2 prompt files and one chat mode; expand later.

---

9) Quality checks (validation gates)

In each prompt file, fix "what counts as done":

• Output format: risk table, unified-diff, checklist.
• Automated checks: build, unit/integration tests, lint/typecheck.
• Manual check: "OK to merge?" with rationale and residual risks.

---

10) Anti-patterns and hacks

• Anti-pattern: one huge instructions.md. Prefer multiple *.instructions.md with applyTo.
• Anti-pattern: generic words instead of rules. Prefer concrete commands/steps.
• Anti-pattern: running dangerous shell commands without a gate. Use deny/allow and manual confirmation.
• Anti-pattern: forgetting specs/memory. Maintain feature.spec.md and project.memory.md.
• Anti-pattern: mixing tasks in one session. Create a Chat Mode per phase.

---

11) Implementation checklist

1. Add .github/copilot-instructions.md (at least 5–8 bullets about build/tests/style).
2. Create 1–2 *.instructions.md with applyTo (frontend/backend or workflows).
3. Add plan.chatmode.md and one prompt (for example, implement-from-spec.prompt.md).
4. Create docs/feature.spec.md and docs/project.memory.md.
5. Include MCP (GitHub MCP at minimum) via .vscode/mcp.json.
6. Run the workflow in VS Code: /implement-from-spec - verify - PR.
7. (Optional) Add a simple AI review in CI via Copilot CLI with strict deny/allow lists.

---

12) Questions and answers (FAQ)

Q: How to ensure Copilot "sees" my instructions? A: Check the response's summary/References; also keep rules short and concrete.

Q: Can I pass parameters dynamically into prompt files? A: Yes, typically via placeholder variables (like ${prNumber}) or simply via the text query when running /prompt in chat.

Q: Where to store secrets for MCP? A: In GitHub Environments or local secret managers; not in .prompt.md/.instructions.md.

Q: Which to choose: Chat Mode vs Prompt File? A: Chat Mode defines the "frame" (model/tools/role). Prompt File is a "scenario" within that frame.

---

13) Next steps

• Add a second prompt for your most frequent manual process.
• Make project.memory.md mandatory after all architecture decisions.
• Gradually move collective knowledge into *.context.md and reference it from prompt files.

---

Appendix A - Quickstart templates

All keys, paths, and flags match the docs (Oct 28, 2025).

/.github/copilot-instructions.md - repository-wide rules

mdCopy
1# Repository coding standards
2- Build: `npm ci && npm run build`
3- Tests: `npm run test` (coverage ≥ 80%)
4- Lint/Typecheck: `npm run lint && npm run typecheck`
5- Commits: Conventional Commits; keep PRs small and focused
6- Docs: update `CHANGELOG.md` in every release PR

/.github/instructions/frontend.instructions.md - path-specific rules

mdCopy
1---
2applyTo: "apps/web/**/*.{ts,tsx},packages/ui/**/*.{ts,tsx}"
3---
4- React: function components and hooks
5- State: Zustand; data fetching with TanStack Query
6- Styling: Tailwind CSS; avoid inline styles except dynamic cases
7- Testing: Vitest + Testing Library; avoid unstable snapshots

/.github/instructions/backend.instructions.md - path-specific rules

mdCopy
1---
2applyTo: "services/api/**/*.{ts,js},packages/server/**/*.{ts,js}"
3---
4- HTTP: Fastify; version APIs under `/v{N}`
5- DB access: Prisma; migrations via `prisma migrate`
6- Security: schema validation (Zod), rate limits, audit logs
7- Testing: integration tests via `vitest --config vitest.integration.ts`

/.github/instructions/actions.instructions.md - GitHub Actions

mdCopy
1---
2applyTo: ".github/workflows/**/*.yml"
3---
4- Keep jobs small; reuse via composite actions
5- Cache: `actions/setup-node` + built-in cache for npm/pnpm
6- Secrets: only through GitHub Environments; never hardcode

/.github/chatmodes/plan.chatmode.md - custom chat mode

mdCopy
1---
2description: "Plan - analyze code/specs and propose a plan; read-only tools"
3model: GPT-4o
4tools:
5  - "search/codebase"
6---
7In this mode:
8- Produce a structured plan with risks and unknowns
9- Do not edit files; output a concise task list instead

/.github/prompts/security-review.prompt.md - prompt file

mdCopy
1---
2mode: 'agent'
3model: GPT-4o
4tools: ['search/codebase']
5description: 'Perform a security review of a pull request'
6---
7Goal: Review PR ${input:prNumber} for common security issues.
8
9Checklist:
10- Authentication/authorization coverage
11- Input validation and output encoding (XSS/SQLi)
12- Secret management and configuration
13- Dependency versions and known CVEs
14
15Output:
16- A Markdown table: issue | file | line | severity | fix
17- If trivial, include a unified diff suggestion

/.github/prompts/implement-from-spec.prompt.md - prompt file

mdCopy
1---
2mode: 'agent'
3model: GPT-4o
4tools: ['search/codebase']
5description: 'Implement a feature from a spec'
6---
7Your task is to implement the feature described in @docs/feature.spec.md.
8
9Steps:
101) Read @docs/feature.spec.md and summarize the plan
112) List files to add or modify
123) Propose code changes; ask before installing new dependencies
134) Generate minimal tests and run them
14
15Validation gates:
16- Build, tests, lint/typecheck must pass
17- Provide a TODO list for anything deferred

/.github/prompts/refactor-slice.prompt.md - prompt file

mdCopy
1---
2mode: 'agent'
3model: GPT-4o
4description: 'Refactor a specific code slice without changing behavior'
5---
6Goal: Improve readability and reduce side effects in @src/feature/* while keeping behavior unchanged.
7Criteria: fewer side effects, clearer structure, all tests pass.

/.github/prompts/test-gen.prompt.md - prompt file

mdCopy
1---
2mode: 'agent'
3model: GPT-4o-mini
4description: 'Generate tests for a given file/module'
5---
6Ask the user to @-mention the target file; generate unit/integration tests and edge cases.

/docs/feature.spec.md - spec skeleton

mdCopy
1# Feature: Export report to CSV
2Goal: Users can export the filtered table to CSV.
3Acceptance criteria:
4- "Export CSV" button on /reports
5- Server generates file ≤ 5s for 10k rows
6- Column order/headers match UI; locale-independent values
7Edge cases: empty values, large numbers, special characters
8Non-goals: XLSX, multi-column simultaneous filters

/.vscode/mcp.json - minimal MCP config

jsonCopy
1{
2  "servers": {
3    "github-mcp": {
4      "type": "http",
5      "url": "https://api.githubcopilot.com/mcp"
6    }
7  }
8}

Appendix B - Operational extras (CLI & CI examples)

These examples complement Appendix A; they cover runtime/automation usage and do not duplicate templates above.

Copilot CLI - safe tool permissions (interactive/CI)

bashCopy
1# Start an interactive session in your repo
2copilot
3
4# Allow/deny specific tools (exact flags per GitHub docs)
5copilot --allow-tool "shell(npm run test:*)" --deny-tool "shell(rm*)"
6
7# Run a prompt file non-interactively (example)
8copilot <<'EOF'
9/security-review prNumber=123
10EOF

GitHub Actions - comment review results on a PR

yamlCopy
1name: AI Security Review (Copilot CLI)
2on:
3  pull_request:
4    types: [opened, synchronize, reopened]
5
6jobs:
7  review:
8    runs-on: ubuntu-latest
9    permissions:
10      contents: read
11      pull-requests: write
12    steps:
13      - uses: actions/checkout@v4
14      - uses: actions/setup-node@v4
15        with:
16          node-version: 22
17      - name: Install Copilot CLI
18        run: npm install -g @github/copilot
19      - name: Run security review prompt
20        env:
21          PR: ${{ github.event.pull_request.number }}
22        run: |
23          copilot --allow-tool "shell(npm run test:*)" --deny-tool "shell(rm*)" <<'EOF'
24          /security-review prNumber=${PR}
25          EOF
26      - name: Post results
27        run: |
28          gh pr comment ${{ github.event.pull_request.number }} --body "Copilot review completed. See artifacts/logs for details."

Sources

Custom chat modes in VS Code

Use MCP servers in VS Code

Adding repository custom instructions for GitHub Copilot

How to build reliable AI workflows with agentic primitives and context engineering

🙌 PS:

Thank you for reading to the end! If the material was useful, we would be very glad if you:

• 💬 Leave a comment or question,
• 📨 Suggest an idea for the next article,
• 🚀 Or simply share it with friends!

Technology becomes more accessible when it is understood. And you have already made the first important step 💪

See you in the next article! Thank you for your support!