DEV Community: Siarhei

From Bolt.new to Production: How I built a React Native app using Copilot and MCP.

Siarhei — Sun, 14 Dec 2025 12:11:07 +0000

When my son was born, my life changed completely. Like any new parent, we needed a way to track sleep, feeding, and diapers. There are a million apps for this, but I wanted something ours. Private, simple, and tailored exactly to what my wife and I needed.

But more than that, I made a challenge to myself: Can I build a full-stack mobile app solo, using all these new AI tools?

I decided to "vibe code" it. No big team, no over-engineering—just me, AI, and a goal.

Here is the story of how I built Zaspa.

The "Magic" Start

I’m a developer, not a designer. Usually, this is where I get stuck. But this time, I leaned heavily on AI.

I started with Bolt.new to generate the initial MVP. It was honestly mind-blowing. It didn't just give me code; it generated the entire design system and the initial screens. I had a working visual prototype almost instantly.

For the splash screens and icons, I didn't hire anyone. I ran Flux (an image generation model) locally on my machine and used ChatGPT to refine the prompts. The result was professional-looking assets for $0.

My wife and I sat down with a simple piece of paper. We listed exactly what features we needed. No Jira, no backlog—just a list on the kitchen table.

The Stack & The Workflow

I went with a stack I could control fully (self-hosted):

Mobile: React Native (Expo)
Backend: Fastify + MongoDB
Web (Landing + Admin): React + Vite
Repo: GitHub

I started coding exclusively with Cursor. It was great... until it wasn't. I burned through my fast tokens incredibly quickly. So, I switched to VS Code + GitHub Copilot. And honestly? It surprised me.

Copilot is powerful, but it can write messy code if you let it. I realized I needed to "manage" it like a junior dev.

Context became king. I created a .github/copilot-instructions.md file to describe the project structure and enforce rules like DRY and SOLID principles. I also added specific Frontend Instructions to enforce component structure (e.g., "Always use SCSS modules for layout and sx prop for dynamic styles").

Custom "Chat Modes" (Prompts)

Instead of typing the same requirements every time, I created reusable prompts that act as "modes" for the AI. I keep these stored in my MCP tool to call them instantly:

Refactoring Mode: "Scan for duplication. Extract logic to custom hooks. Ensure design consistency. DO NOT change functionality."
Frontend Mode: "You are a Senior React Native Dev. Use functional components, strict TypeScript, and our specific folder structure."
Testing Mode: "Write unit tests for this component using Jest. Cover edge cases first."

(I wrote a detailed guide on this workflow here).

This simple system saved me from the "spaghetti code" that AI often generates after a few hours of coding.

Where it got real (The Roadblocks)

It wasn't all smooth sailing. I hit two major walls.

The Firebase Nightmare
I wanted push notifications and analytics, so I reached for the standard: Firebase. Big mistake. Integrating Firebase with React Native was a dependency hell. Version conflicts everywhere. I spent days fighting build errors instead of coding.

So I ditched it. I switched to Expo Push Services which just works. For analytics, I wrote my own lightweight JS logic to send simple events (install, screen view) to my Fastify backend. I built a custom Admin Dashboard to show daily/weekly stats. Now I own my data, and the app is lighter.

Localization Hell
My wife and I speak different languages. We understand each other, but for the app, multi-language support was non-negotiable.

At first, I just hardcoded JSON files. But as I refactored the code (thanks to my "Refactoring Mode"), the localization files became a mess. Huge JSON files, hundreds of "orphan" keys for buttons I deleted weeks ago, and duplicates like button.save, common.save, actions.save.

I was spending more time managing en.json than playing with my son.

The Fix (and how I accidentally built a startup)
I couldn't find a tool that worked inside my IDE properly, so I built one. I created goman.live, an MCP server that integrates directly with Cursor/Copilot.

Instead of editing JSON, I just tell the AI: "Add a translation for this button."
The agent:

Checks if the key exists (deduplication).
Adds translations for all languages automatically.
Audits the files for unused keys.

It started as a script for Zaspa, but it worked so well I released it. It turned a headache into a background task.

Launch & Reality

I didn't do a big Product Hunt launch. I just wrote a few posts on Reddit and shared it in local Telegram channels for parents.

Currently, we have about 20-30 organic installs per month. But most importantly, it's used daily by my family.

Building Zaspa proved to me that one person can build a complex, full-stack product if they use AI correctly. But you can't trust AI blindly—you need to guide it with context and strict rules. And don't over-engineer early; sometimes a custom solution is faster than fighting with a massive library like Firebase.

MCP Tools Used:

GitHub: For repo management.
MongoDB: For database interactions.
goman.live: For localization & prompt management.
Postman: For API testing.

Goman.live: Guide for AI Developers and Vibe Coders

Siarhei — Wed, 10 Dec 2025 15:10:07 +0000

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:

Autopilot (via MCP): You simply ask your AI agent in the IDE to "add a button", and everything happens by itself.
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.
🎬 See it in action: Init Demo
🎬 See it in action: Adding Spanish language support

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:

The agent checks if such a key exists (to avoid duplicates).
Generates translations into all languages supported by the project.
Saves them to the database.
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:

Automatic Syntax Check: The service watches so AI doesn't break variables (e.g., {{name}}) or HTML tags.
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.

Speed: Localization becomes part of writing code, not a separate stage.
Quality: AI knows context and style better than Google Translate.
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 😉).

I built a free baby tracker that syncs across devices without requiring an account

Siarhei — Mon, 01 Dec 2025 09:30:48 +0000

Hey everyone! I recently became a dad, and let me tell you - nobody warns you about the logistics nightmare that comes with a newborn.

The Problem

First few days home, we tried tracking everything on paper. Feeding times, which breast, how long, diaper changes, sleep... The notebook quickly became an unreadable mess. Then came the constant texts between me and my wife: "When did you last feed her?" "Which side?" "Did you change her?" "How long has she been sleeping?"

We tried existing baby tracker apps. One wanted us to create accounts and verify emails - not happening at 3 AM with a screaming baby. Another had half the features locked behind a $10/month subscription. A third one had sync, but required both of us to sign up separately and then somehow "connect" our accounts through a confusing process.

I just wanted something simple. Log stuff. Share with my wife. That's it.

The Solution (That Grew Into Something More)

So I built a quick app for myself. Just feedings at first - tap, log, done. Shared it with my wife through a simple sync key.

Then we needed sleep tracking. Added that. Then diapers. Then weight for doctor visits. Then a timer because we kept forgetting when the feeding started. Then dark mode because I blinded myself one too many times at night.

Two months later, that "quick app" became Zaspa - a full baby tracker that actually solves the problems we had.

What Makes It Different

No accounts, no passwords, no BS - You generate a random sync key, text it to your partner, they enter it, done. You're both tracking the same baby in real-time. No email verification, no "forgot password", no account management. Your data stays anonymous on our servers - we don't store baby names or any personal info.

Actually works at 3 AM - Big buttons, one-handed operation, minimal steps to log anything. When you're half-asleep holding a baby, you don't want to navigate through menus.

Fix mistakes easily - Forgot to log a feeding an hour ago? Just adjust the timestamp. Started the timer late? Edit the start time. Life with a newborn is messy, the app handles that.

Key Features for Parents

Feeding tracker - Breastfeeding with side switching, formula with amounts, solid foods when you get there. Built-in timer so you don't have to watch the clock.

Sleep tracker - Log naps and night sleep. Timer for real-time tracking. Helps you spot patterns in your baby's schedule (if they have one).

Diaper log - Quick taps for wet/dirty. Simple but important for making sure baby is eating enough.

Growth tracking - Weight and height over time. Have real data ready when the pediatrician asks "how's the weight gain?"

Activity log - Walks, baths, tummy time, medicine, pumping. Notes on everything.

Excel export - Generate spreadsheets for doctor visits. No more "I think she ate around... maybe 6 times yesterday?"

Multiple kids - Twins? Toddler and newborn? Separate profiles for each.

Dark mode - Your eyes will thank you.

6 languages - English, Spanish, German, Ukrainian, Belarusian, Polish.

Completely Free

No ads. No premium tier. No subscriptions. I built this because my family needed it, and I figured other parents might too.

Try It

https://zaspa.online/

Works on iOS, Android. Your data is encrypted and private. You can disconnect sync anytime and keep everything local.

Would love to hear from other parents - what's missing? What would make this actually useful for your situation?

Thanks for checking it out!

MCP servers I use for vibecoding in my daily life

Siarhei — Mon, 01 Dec 2025 09:10:35 +0000

Today, I want to share a brief list of MCP servers that I use daily in my work and projects.

1. GitHub MCP Server

What It Does

GitHub MCP Server enables you to work with GitHub through an AI assistant: view code, search for files, read and summarize documentation in repositories, manage issues and pull requests, and get an overall view of projects.

How I Use It

I read and create documentation in repositories.
I add to or create new technical documentation.
I analyze pull requests (what has changed, what risks are involved, what needs to be amended) with the help of rules that impose code style restrictions.
I create pull requests.
I look at issues that are relevant to me to understand what to prioritize. This significantly reduces the number of switches between the IDE and the browser, especially when you need to quickly dive into several PRs at once.

Who it's suitable for

Developers who "live" in the IDE and dislike constantly opening GitHub in the browser.
Those who work extensively with PRs and technical documentation.

Links

GitHub MCP

Atlassian MCP Server (Jira / Confluence)

What it does

The Atlassian MCP Server provides access to Jira and Confluence through an AI assistant. You can create and update tasks, read pages in Confluence, search for information, and receive summaries of documentation and backlogs.

How I Use It

I read large Confluence pages and receive concise summaries instead of manually scrolling.
I write and refine technical documentation, such as design documents, meeting notes, and instructions.
I create tasks in Jira (bug, task, sub-task) from simple text notes.
I edit existing tasks, including descriptions, acceptance criteria, status, and priorities.
I quickly review tasks that are specifically relevant to me, such as those in progress, those "to do," and those that are blocked. In fact, this is my primary way of working with Jira without delving into its cumbersome web interface.

Who it's suitable for:

PMs, BAs, Team/Tech Leads who "live" in Jira and Confluence.
Engineers who want to see "what is expected of me" in a convenient text format.
Teams with a lot of documentation and lengthy Confluence pages.

Links:

Atlassian MCP

Figma MCP Server

What it does

Figma MCP Server integrates design context into the assistant, including frames, components, styles, tokens, and layouts. It helps transfer designs from Figma to code by understanding the screen structure, spacing, component names, and connections between elements.

How I use it

It significantly simplifies the writing of components, especially when the screen is complex.
I obtain the frame structure and can easily transfer it into code.
I make fewer mistakes in details: consistent spacing, correct colors, and text styles. As a result, the time from "design is in Figma" to "screen is functional in code" is reduced, and the implementation quality is closer to the original design.

Who it's for

Frontend developers who work extensively with Figma.
Designers and engineers who want to minimize manual adjustments when transferring designs to code.
Teams with a complete design system and tokens.

Links

Figma MCP

Goman.live – MCP Localization Manager

What it does

Through MCP, Goman.live assists with localization: creating new keys, viewing existing ones, obtaining draft translations in multiple languages without manually editing JSON files, and translating texts without losing context.

How I Use It

During vibe coding, when it's clear that the text will need translation.
In projects that require localization into multiple languages (I have several such projects).
When new keys need to be quickly added and a draft translation obtained, which can then be properly reviewed on the service page.

At the moment, I am satisfied: the localization process has become more predictable and less stressful. However, it is important to monitor the relevance of the keys, as agents tend to create a lot of irrelevant ones.

Who it's suitable for

Teams that require internationalization (i18n) and support multiple interface languages.
Developers who prefer not to manually maintain JSON translation files.
Localizers and content teams seeking a centralized location for translations.

Links

MCP Localization Manager

Playwright MCP

What it does

Playwright MCP allows you to control the browser through an assistant based on Playwright: open pages, fill out forms, click buttons, check tables, and read texts on the page. It works with the semantic structure (a11y tree) rather than "screen images," making it more stable in its operations.

How I Use It / When It's Useful

For simple smoke tests of main user scenarios (login, checkout, order form, etc.).
For quickly checking that key flows haven't broken after changes.
For gathering information from pages without writing full e2e tests manually.

This isn't a magical replacement for all tests, but it's a good tool to give agents access to the browser and automate routine checks.

Who It's Suitable For

QA professionals who are already using Playwright.
For developers who want to easily verify main scenarios after changes.
For analysts who need to automatically extract data from web pages.

Links

Playwright MCP

Brief Conclusion

Atlassian MCP — My main tool for documentation and tasks (Jira/Confluence).
GitHub MCP — For code, PRs, and repository reviews.
Figma MCP — For implementing designs and staying close to the layout.
Goman MCP — when a project requires localization in multiple languages.
Playwright MCP — used for UI automation, smoke testing, and verifying main user scenarios.

MCP servers I use in my daily life

Siarhei — Mon, 01 Dec 2025 07:48:12 +0000

Today, I want to share a brief list of MCP servers that I use daily in my work and projects.

1. GitHub MCP Server

What It Does

How I Use It

I read and create documentation in repositories.
I add to or create new technical documentation.
I analyze pull requests (what has changed, what risks are involved, what needs to be amended) with the help of rules that impose code style restrictions.
I create pull requests.
I look at issues that are relevant to me to understand what to prioritize. This significantly reduces the number of switches between the IDE and the browser, especially when you need to quickly dive into several PRs at once.

Who it's suitable for

Developers who "live" in the IDE and dislike constantly opening GitHub in the browser.
Those who work extensively with PRs and technical documentation.

Links

GitHub MCP

Atlassian MCP Server (Jira / Confluence)

What it does

How I Use It

I read large Confluence pages and receive concise summaries instead of manually scrolling.
I write and refine technical documentation, such as design documents, meeting notes, and instructions.
I create tasks in Jira (bug, task, sub-task) from simple text notes.
I edit existing tasks, including descriptions, acceptance criteria, status, and priorities.
I quickly review tasks that are specifically relevant to me, such as those in progress, those "to do," and those that are blocked. In fact, this is my primary way of working with Jira without delving into its cumbersome web interface.

Who it's suitable for:

PMs, BAs, Team/Tech Leads who "live" in Jira and Confluence.
Engineers who want to see "what is expected of me" in a convenient text format.
Teams with a lot of documentation and lengthy Confluence pages.

Links:

Atlassian MCP

Figma MCP Server

What it does

How I use it

It significantly simplifies the writing of components, especially when the screen is complex.
I obtain the frame structure and can easily transfer it into code.
I make fewer mistakes in details: consistent spacing, correct colors, and text styles. As a result, the time from "design is in Figma" to "screen is functional in code" is reduced, and the implementation quality is closer to the original design.

Who it's for

Frontend developers who work extensively with Figma.
Designers and engineers who want to minimize manual adjustments when transferring designs to code.
Teams with a complete design system and tokens.

Links

Figma MCP

Goman.live – MCP Localization Manager

What it does

How I Use It

During vibe coding, when it's clear that the text will need translation.
In projects that require localization into multiple languages (I have several such projects).
When new keys need to be quickly added and a draft translation obtained, which can then be properly reviewed on the service page.

Who it's suitable for

Teams that require internationalization (i18n) and support multiple interface languages.
Developers who prefer not to manually maintain JSON translation files.
Localizers and content teams seeking a centralized location for translations.

Links

MCP Localization Manager

Playwright MCP

What it does

How I Use It / When It's Useful

For simple smoke tests of main user scenarios (login, checkout, order form, etc.).
For quickly checking that key flows haven't broken after changes.
For gathering information from pages without writing full e2e tests manually.

This isn't a magical replacement for all tests, but it's a good tool to give agents access to the browser and automate routine checks.

Who It's Suitable For

QA professionals who are already using Playwright.
For developers who want to easily verify main scenarios after changes.
For analysts who need to automatically extract data from web pages.

Links

Playwright MCP

Brief Conclusion

Atlassian MCP — My main tool for documentation and tasks (Jira/Confluence).
GitHub MCP — For code, PRs, and repository reviews.
Figma MCP — For implementing designs and staying close to the layout.
Goman MCP — when a project requires localization in multiple languages.
Playwright MCP — used for UI automation, smoke testing, and verifying main user scenarios.

LangGraph for Beginners: A Complete Guide

Siarhei — Fri, 28 Nov 2025 09:56:32 +0000

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

    Typical Graph:              Subway Map (Analogy):

        [A]                         [Victory Square]
         │                                 │
         ▼                                 ▼
        [B]───────►[C]              [October]───►[Kupala]
         │                                 │
         ▼                                 ▼
        [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

Typical Chain:

    Question → LLM → Answer

    or

    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

LangGraph (Graph):

                    ┌──────────────────────┐
                    │                      │
                    ▼                      │
    Question → [Researcher] → [Writer] → [Reviewer]
                                               │
                                               ▼
                                          Good? ───NO───► back to Writer
                                               │
                                              YES
                                               │
                                               ▼
                                           [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.

┌─────────────────────────────────────────────────────────────┐
│                        STATE (Стан)                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   topic: "What I Write"                                     │
│   research: "Materials from the Researcher"                 │
│   draft: "Draft from the Writer"                            │
│   review: "Comments from the Reviewer"                      │
│   finalArticle: "Final Article"                             │
│   messages: [history of all messages]                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘
              ▲               ▲               ▲
              │               │               │
         Researcher        Writer         Reviewer
      (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:

┌─────────────────────────────────────────┐
│            EMPLOYEE SURVEY              │
├─────────────────────────────────────────┤
│ Name: ___________________               │
│ Age: _____                              │
│ Work Experience (years): _____          │
│ Skills List: ___, ___, ___              │
└─────────────────────────────────────────┘

In code, it looks like this:

// ANALOGY: Creating a survey form
const Survey = {
    name: '', // Text field
    age: 0, // Number
    experience: 0, // Number
    skills: [], // List
};

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.

import { Annotation } from '@langchain/langgraph';

const ResearchState = Annotation.Root({
    // Each field is described through Annotation<Type>
    topic: Annotation<string>({...}),
    research: Annotation<string>({...}),
    draft: Annotation<string>({...}),
    // etc.
});

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?

Agent 1 writes: topic = "Topic A"
Agent 2 writes: topic = "Topic B"

What should be in topic? "Topic A"? "Topic B"? "Topic A + Topic B"?

Solution: Reducer - a function that resolves

Reducer is a function that takes:

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

It returns: result (what to keep)

reducer: (current, update) => result;
//         ▲         ▲           ▲
//         │         │           └── What will be kept
//         │         └── New value
//         └── Current value

Examples of Reducers:

1. Reducer "REPLACE"

The new value completely replaces the old one.

// Code:
reducer: (current, update) => update;

// Example:
// Current: "Theme A"
// New:     "Theme B"
// Result:   "Theme B"  ← new replaces old

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

file.txt
──────────────
Was:   "Old text"
        ▼ (overwrite)
Is:    "New text"

2. Reducer "APPEND"

New elements are added to the existing ones.

// Code:
reducer: (current, update) => [...current, ...update];

// Example:
// Current: ["Message 1", "Message 2"]
// New:     ["Message 3"]
// Result:   ["Message 1", "Message 2", "Message 3"]

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

diary.txt
──────────────
Was:    "Monday: did A"
        "Tuesday: did B"
             ▼ (adding)
Became: "Monday: did A"
        "Tuesday: did B"
        "Wednesday: did C" ← added

Full example of the state:

const ResearchState = Annotation.Root({
    // ═══════════════════════════════════════════════════════
    // FIELD: messages (messages)
    // ═══════════════════════════════════════════════════════
    messages: Annotation<BaseMessage[]>({
        // REDUCER: Add new messages to existing ones
        reducer: (current, update) => [...current, ...update],
        // DEFAULT: Initial value - empty array
        default: () => [],
    }),
    //
    // How it works:
    // 1. Beginning:    messages = []
    // 2. Researcher:  messages = [] + [AIMessage] = [AIMessage]
    // 3. Writer: messages = [AIMessage] + [AIMessage] = [AIMessage, AIMessage]
    // 4. And so on - all messages are stored

    // ═══════════════════════════════════════════════════════
    // FIELD: topic (topic)
    // ═══════════════════════════════════════════════════════
    topic: Annotation<string>({
        // REDUCER: Replace old value with new one
        reducer: (_, update) => update, // "_" means "ignore"
        default: () => '',
    }),
    //
    // How it works:
    // 1. Beginning:    topic = ""
    // 2. User:   topic = "" → "LangChain"
    // If someone else writes in topic - the old value will disappear

    // ═══════════════════════════════════════════════════════
    // FIELD: iterationCount (iteration counter)
    // ═══════════════════════════════════════════════════════
    iterationCount: Annotation<number>({
        reducer: (_, update) => update, // Simply replace
        default: () => 0, // Start from 0
    }),
    //
    // The writer writes each time: iterationCount: state.iterationCount + 1
    // 1. Start:         iterationCount = 0
    // 2. Writer (1):   iterationCount = 0 + 1 = 1
    // 3. Writer (2):   iterationCount = 1 + 1 = 2
    // 4. Writer (3): iterationCount = 2 + 1 = 3
});

Visualization of Reducers:

┌─────────────────────────────────────────────────────────────────┐
│                       REDUCER: REPLACE                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   Current: █████████████  "Old text"                            │
│                  ▼                                              │
│   New:     ░░░░░░░░░░░░░  "New text"                            │
│                  ▼                                              │
│   Result:  ░░░░░░░░░░░░░  "New text" ← only new                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                         REDUCER: ADD                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   Current:  [█] [█] [█]      ← three elements                   │
│                  +                                              │
│   New:      [░] [░]          ← two new                          │
│                  =                                              │
│   Result:   [█] [█] [█] [░] [░]  ← all together                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

What is default?

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

default: () => 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!

// POOR: If this is an object or array
default: []  // All instances will refer to the same array!

// GOOD: The function creates a new array each time
default: () => []  // Each instance will get its own array

Examples:

// For a string
default: () => ''        // Empty string

// For a number
default: () => 0         // Zero

// For an array
default: () => []        // Empty array

// For an object
default: () => ({})      // Empty object

// For boolean
default: () => false     // false

PART 3: Nodes - Agents

What is a node?

Node is a function that:

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

Analogy: Worker on the Assembly Line

┌─────────────────────────────────────────────────────────────┐
│                       ASSEMBLY LINE                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   [Box] ──► [Worker 1] ───────► [Worker 2] ──────►          │
│                  │                    │                     │
│                  ▼                    ▼                     │
│            Adds part A          Adds part B                 │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Each worker:
1. Sees what has already been done (state)
2. Does their part of the work
3. Passes it on with additions

Node Structure in Code:

async function myNode(
    state: ResearchStateType // ← INPUT: Full state
): Promise<Partial<ResearchStateType>> {
    // ← OUTPUT: Partial update
    // 1. Read data from state
    const data = state.someField;

    // 2. Do the work
    const result = await doSomething(data);

    // 3. Returning the update (only what has changed)
    return {
        someField: result,
    };
}

Important: Partial

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.

// The full state has 6 fields:
state = {
    topic: "...",
    research: "...",
    draft: "...",
    review: "...",
    finalArticle: "...",
    messages: [...],
    iterationCount: 0
}

// But the node can only return what it has changed:
return {
    draft: "New draft",           // Changed
    messages: [new AIMessage("...")], // Added
    // The other fields are not mentioned - they will remain as they were
}

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.

async function researcherNode(
    state: ResearchStateType
): Promise<Partial<ResearchStateType>> {
    // ┌─────────────────────────────────────────────────────────────┐
    // │ STEP 1: Get the topic for research                         │
    // └─────────────────────────────────────────────────────────────┘
    const topic =
        state.topic ||
        String(state.messages[state.messages.length - 1]?.content) ||
        '';
    //            ▲               ▲
    //            │               └── Or the last message
    //            └── First, try to take topic

    // ┌─────────────────────────────────────────────────────────────┐
    // │ STEP 2: Form the prompt for LLM                            │
    // └─────────────────────────────────────────────────────────────┘
    const prompt = `You are an expert researcher. Your task is to gather key information.
    Topic: ${topic}
    Conduct a brief research...`;

    // ┌─────────────────────────────────────────────────────────────┐
    // │ STEP 3: Call LLM                                           │
    // └─────────────────────────────────────────────────────────────┘
    const response = await model.invoke([
        { role: 'system', content: prompt }, // Instructions for AI
        { role: 'user', content: `Research the topic: ${topic}` }, // Request
    ]);

    const research = String(response.content); // Result from LLM

    // ┌─────────────────────────────────────────────────────────────┐
    // │ STEP 4: Return state update                                │
    // └─────────────────────────────────────────────────────────────┘
    return {
        research, // Store the research result
        messages: [
            new AIMessage({
                content: `[Research completed]
${research}`,
            }),
        ],
        // ▲ Add a message to the history
    };
}

What happens:

INPUT (state):                       OUTPUT (update):
┌─────────────────────┐              ┌─────────────────────┐
│ topic: "LangChain"  │              │ research: "LangCh.. │
│ research: ""        │  ──────►     │ messages: [+1 msg]  │
│ draft: ""           │              └─────────────────────┘
│ messages: [1 msg]   │
└─────────────────────┘
                                     ▼ After merging:

                                ┌─────────────────────┐
                                │ topic: "LangChain"  │
                                │ research: "LangCh...│ ← updated
                                │ draft: ""           │
                                │ messages: [2 msgs]  │ ← added
                                └─────────────────────┘

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.

async function writerNode(
    state: ResearchStateType
): Promise<Partial<ResearchStateType>> {
    // ┌─────────────────────────────────────────────────────────────┐
    // │ STEP 1: Read the research and possible review              │
    // └─────────────────────────────────────────────────────────────┘
    const prompt = `You are a technical writer. Based on the research, write an article.

Research:
${state.research}

${state.review ? `Previous review (consider comments): ${state.review}` : ''}
`;

    // ┌─────────────────────────────────────────────────────────────┐
    // │ STEP 2: Call LLM                                           │
    // └─────────────────────────────────────────────────────────────┘
    const response = await model.invoke([
        { role: 'system', content: prompt },
        { role: 'user', content: 'Write an article based on the research' },
    ]);

    const draft = String(response.content);

    // ┌─────────────────────────────────────────────────────────────┐
    // │ STEP 3: Return the update                                  │
    // └─────────────────────────────────────────────────────────────┘
    return {
        draft, // Draft of the article
        iterationCount: state.iterationCount + 1, // Increment the counter
        messages: [
            new AIMessage({ content: `[Draft ${state.iterationCount + 1}]` }),
        ],
    };
}

What happens on repeat call:

FIRST CALL:                          SECOND CALL (after review):
┌─────────────────────┐              ┌─────────────────────┐
│ research: "..."     │              │ research: "..."     │
│ review: ""          │              │ review: "Refine..." │ ← there are comments!
│ iterationCount: 0   │              │ iterationCount: 1   │
└─────────────────────┘              └─────────────────────┘
         │                                    │
         ▼                                    ▼
Writing without comments             Considering comments
         │                                    │
         ▼                                    ▼
┌─────────────────────┐              ┌─────────────────────┐
│ draft: "Version 1"  │              │ draft: "Version 2"  │
│ iterationCount: 1   │              │ iterationCount: 2   │
└─────────────────────┘              └─────────────────────┘

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.

async function reviewerNode(state: ResearchStateType): Promise<Partial<ResearchStateType>> {

    // ┌─────────────────────────────────────────────────────────────┐
    // │ STEP 1: Formulating the review request                      │
    // └─────────────────────────────────────────────────────────────┘
    const prompt = `You are a strict editor. Evaluate the article.

Article:
${state.draft}

Evaluate based on the criteria:
1. Accuracy of information
2. Structure and logic
3. Language quality
4. Completeness of the topic coverage

If the article is good - say "APPROVED". When improvements are needed, please provide specific recommendations.
`;

    // ┌─────────────────────────────────────────────────────────────┐
    // │ STEP 2: Get the review                                     │
    // └─────────────────────────────────────────────────────────────┘
    const response = await model.invoke([...]);
    const review = String(response.content);

    // ┌─────────────────────────────────────────────────────────────┐
    // │ STEP 3: Return the review                                  │
    // └─────────────────────────────────────────────────────────────┘
    return {
        review,  // Review (either "APPROVED" or comments)
        messages: [new AIMessage({ content: `[Review]\n${review}` })],
    };
}

Two possible outcomes:

OPTION A: The article is good             OPTION B: Needs improvement
┌───────────────────────────┐             ┌───────────────────────────┐
│ review: "APPROVED.        │             │ review: "Improve:         │
│ The article is excellent!"│             │ 1. Add examples           │
│                           │             │ 2. Clarify the terms"     │
└───────────────────────────┘             └───────────────────────────┘
             │                                        │
             ▼                                        ▼
        Moving to                              Returning to
        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.

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

What happens:

INPUT:                              OUTPUT:
┌─────────────────────┐             ┌─────────────────────┐
│ draft: "Ready..."   │  ──────►    │ finalArticle:       │
│ finalArticle: ""    │             │   "Ready..."        │
└─────────────────────┘             └─────────────────────┘

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

Recipe steps:

    [Make dough] ────► [Add sauce] ────► [Add cheese] ────► [Bake]
          │                  │                  │               │
          ▼                  ▼                  ▼               ▼
      TRANSITION         TRANSITION        TRANSITION         END

Two Types of Transitions in LangGraph:

1. Simple Transitions (addEdge)

Always go to the same node.

workflow.addEdge('researcher', 'writer');
//                    ▲            ▲
//                    │            └── Where are we going
//                    └── From where are we coming

// Meaning: After researcher, we ALWAYS go to writer

Visualization:

    [researcher] ───────────────► [writer]
                   (always)

2. Conditional Transitions (addConditionalEdges)

The choice of the next node depends on the state.

workflow.addConditionalEdges(
    'reviewer', // Source node
    shouldContinue, // Function that decides where to go
    {
        writer: 'writer', // If the function returns 'writer' → go to writer
        finalizer: 'finalizer', // If the function returns 'finalizer' → go to finalizer
    }
);

Visualization:

                            ┌──────────► [writer]
                            │
    [reviewer] ─────► [?] ──┤
                            │
                            └──────────► [finalizer]

    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.

function shouldContinue(state: ResearchStateType): 'writer' | 'finalizer' {
    //                                              ▲
    //                                              └── Returns one of these strings

    const review = state.review.toLowerCase();
    const maxIterations = 3;

    // ═══════════════════════════════════════════════════════════════
    // CONDITION 1: Reviewer said "APPROVED"
    // ═══════════════════════════════════════════════════════════════
    if (review.includes('зацверджана') || review.includes('approved')) {
        console.log('Article approved');
        return 'finalizer'; // ← Proceed to finalize
    }

    // ═══════════════════════════════════════════════════════════════
    // CONDITION 2: Too many attempts (protection against infinite loop)
    // ═══════════════════════════════════════════════════════════════
    if (state.iterationCount >= maxIterations) {
        console.log('Maximum iterations reached');
        return 'finalizer'; // ← Force finalize
    }

    // ═══════════════════════════════════════════════════════════════
    // OTHERWISE: Needs revision
    // ═══════════════════════════════════════════════════════════════
    console.log('Revision needed');
    return 'writer'; // ← Go back to writer
}

Decision flowchart:

                         ┌───────────────────┐
                         │  shouldContinue   │
                         │    (function)     │
                         └─────────┬─────────┘
                                   │
                                   ▼
                    ┌──────────────────────────────┐
                    │   Is "approved" present      │
                    │   in the review?             │
                    └──────────────┬───────────────┘
                                   │
                      ┌────────────┴────────────┐
                      │                         │
                     YES                       NO
                      │                         │
                      ▼                         ▼
               ┌────────────┐      ┌──────────────────────────┐
               │  return    │      │ Is iterationCount >= 3?  │
               │'finalizer' │      └──────────────┬───────────┘
               │            │                     │
               └────────────┘        ┌────────────┴────────────┐
                                     │                         │
                                    YES                       NO
                                     │                         │
                                     ▼                         ▼
                              ┌────────────┐            ┌────────────┐
                              │  return    │            │  return    │
                              │'finalizer' │            │  'writer'  │
                              │            │            │            │
                              └────────────┘            └────────────┘

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:

// ═══════════════════════════════════════════════════════════════
// STEP 1: Create StateGraph with our state
// ═══════════════════════════════════════════════════════════════
const workflow = new StateGraph(ResearchState)

    // ═══════════════════════════════════════════════════════════
    // STEP 2: Add nodes (register functions)
    // ═══════════════════════════════════════════════════════════
    .addNode('researcher', researcherNode) // Name 'researcher' → function
    .addNode('writer', writerNode) // Name 'writer' → function
    .addNode('reviewer', reviewerNode) // Name 'reviewer' → function
    .addNode('finalizer', finalizerNode) // Name 'finalizer' → function

    // ═══════════════════════════════════════════════════════════
    // STEP 3: Add simple transitions
    // ═══════════════════════════════════════════════════════════
    .addEdge('__start__', 'researcher') // Start → Researcher
    .addEdge('researcher', 'writer') // Researcher → Writer
    .addEdge('writer', 'reviewer') // Writer → Reviewer

    // ═══════════════════════════════════════════════════════════
    // STEP 4: Add conditional transition
    // ═══════════════════════════════════════════════════════════
    .addConditionalEdges('reviewer', shouldContinue, {
        writer: 'writer', // If 'writer' → back to writer
        finalizer: 'finalizer', // If 'finalizer' → to finalizer
    })

    // ═══════════════════════════════════════════════════════════
    // STEP 5: Add final transition
    // ═══════════════════════════════════════════════════════════
    .addEdge('finalizer', '__end__'); // Finalizer → End

Special nodes:

┌───────────────┬─────────────────────────────────────────────┐
│  '__start__'  │  Virtual start node                         │
│               │  LangGraph automatically starts from it     │
├───────────────┼─────────────────────────────────────────────┤
│  '__end__'    │  Virtual end node                           │
│               │  When reached - the graph is completed      │
└───────────────┴─────────────────────────────────────────────┘

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.

// Graph description (blueprint)
const workflow = new StateGraph(ResearchState)
    .addNode(...)
    .addEdge(...);

// Compilation into an executable program
const app = workflow.compile();
//    ▲
//    └── Now this can be run!

Analogy: Recipe vs. Finished Dish

workflow (description)                 app (compiled program)
──────────────────────                 ──────────────────────
Recipe on paper                        Ready pizza
   - How to make the dough                (can be eaten)
   - What to add
   - How to bake

Cannot be eaten!                       Can be eaten!

Checkpointer (MemorySaver)

What is it?

Checkpointer is a mechanism for saving state after each step.

import { MemorySaver } from '@langchain/langgraph';

const checkpointer = new MemorySaver();

const app = workflow.compile({
    checkpointer, // ← Adding checkpointer
});

Why is this needed?

WITHOUT CHECKPOINTER:
═════════════════════════════════════════════════════════════════

    Run 1:   START → researcher → writer → ... → END

    Run 2:   START → researcher → ... (everything from the beginning!)

    ✗ Cannot continue from the stopping point
    ✗ Cannot view history


WITH CHECKPOINTER:
═════════════════════════════════════════════════════════════════

    Run 1:   START → researcher → [SAVED]
                                      │
                               thread_id: "chat-123"

    Run 2:   [RESUMING] → writer → reviewer → ...
                     │
              thread_id: "chat-123"

    ✓ Can continue from the stopping point
    ✓ Can view history
    ✓ Can have multiple independent "conversations"

Thread ID - identifier of the "thread"

const config = {
    configurable: {
        thread_id: 'article-1', // Unique ID for this "conversation"
    },
};

// Each thread_id is a separate story
// 'article-1' - about one article
// 'article-2' - about another article
// 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

const result = await app.invoke(
    // Initial data for the state
    {
        topic: 'Benefits of LangChain',
        messages: [new HumanMessage('Benefits of LangChain')],
    },
    // Configuration
    {
        configurable: {
            thread_id: 'article-1',
        },
    }
);

What Happens When `invoke()` is Called:

┌─────────────────────────────────────────────────────────────────┐
│                         invoke()                                │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│ 1. INITIALIZATION OF STATE                                      │
│    state = {                                                    │
│        topic: "Advantages of LangChain",                        │
│        messages: [HumanMessage],                                │
│        research: "",  ← default                                 │
│        draft: "",     ← default                                 │
│        review: "",    ← default                                 │
│        finalArticle: "", ← default                              │
│        iterationCount: 0, ← default                             │
│    }                                                            │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. BEGINNING: __start__ → researcher                            │
│    Executing researcherNode(state)                              │
│    → Receiving update {research: "...", messages: [...]}        │
│    → Merging with state through reducers                        │
│    Saving checkpoint                                            │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. TRANSITION: researcher → writer                              │
│    Execute writerNode(state)                                    │
│    → Receive update {draft: "...", iterationCount: 1}           │
│    → Merge with state                                           │
│    Save checkpoint                                              │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│ 4. TRANSITION: writer → reviewer                                │
│    Execute reviewerNode(state)                                  │
│    → Receive update {review: "..."}                             │
│    → Merge with state                                           │
│    Save checkpoint                                              │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│ 5. CONDITIONAL TRANSITION: shouldContinue(state)                │
│    → Returns 'writer' or 'finalizer'                            │
│    → If 'writer' - return to step 3                             │
│    → If 'finalizer' - proceed further                           │
└───────────────────────────────┬─────────────────────────────────┘
                                │ (if 'finalizer')
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│ 6. TRANSITION: reviewer → finalizer                             │
│    Execute finalizerNode(state)                                 │
│    → Receive update {finalArticle: "..."}                       │
│    → Merge with state                                           │
│    Save checkpoint                                              │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│ 7. FINALIZER: finalizer → __end__                               │
│    The graph has completed                                      │
│    Returning the final state                                    │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
                        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:

.addEdge('success', '__end__')
.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:

Build your own agent system - Start with a simple two-node graph and gradually add complexity
Experiment with different flows - Try creating graphs with multiple conditional branches
Add persistence - Use MemorySaver or database-backed checkpointers for production
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! 🚀

How to Work with Feedback in Prompting: A Live Guide with Examples

Siarhei — Tue, 25 Nov 2025 16:12:16 +0000

Hello, everyone!

We continue our wonderful series of articles on prompting 🤖✨

Today, we will explore four effective feedback prompting techniques that will help you achieve even better results from AI! 🚀

🧠 What Are These Techniques and Where Did They Come From?

To work with AI as efficiently as possible, experts have developed a range of powerful techniques 🛠️. They were born at the intersection of science, engineering practice, and everyday user experience.

Main methods of feedback prompting:

✍️ Explicit Feedback Prompting — open expression of comments and suggestions.
🔄 Iterative Refinement — gradual refinement of responses through multiple iterations.
🧐 Critique and Revision Prompting — the model critiques and improves the results itself.
🧩 RLHF (Reinforcement Learning from Human Feedback) — choosing the best from several options. ---

✍️ 1. Explicit Feedback Prompting

Let's start with a simple yet very effective method!

What it is:

You provide the model with specific and polite feedback 📜: what needs to be changed and how to improve the response.

When useful:

When the first response seems superficial or incomplete 🔍

How it looks:

Prompt:

Write an article about interesting facts about Antarctica.

First response:

Antarctica is a cold continent. There is almost no vegetation or animals here.

Feedback:

The text seems too general.
Please add specific data about temperatures, research stations, and local fauna.

Revised Response:

Antarctica is the coldest continent, where the average winter temperature can reach -60°C.
There are approximately 70 research stations, and the known animals include emperor penguins and Weddell seals.

🔄 2. Iterative Refinement

Let's continue! Let's see how you can refine results step by step 🔧

What it is:

Gradual refinement and improvement of responses in multiple stages.

When it's useful:

When you want to achieve maximum quality ✨

Prompt 1:

Write a summary of the book "1984" by George Orwell.

Response:

"1984" is a novel about a totalitarian state where the protagonist, Winston, tries to resist the system.

Feedback:

Add more emotional moments and emphasize Winston's fear of Big Brother

Revised Response:

"1984" tells the story of life under total surveillance, where Winston Smith lives in constant fear and tries to maintain his humanity.

And so on. In this way, we refine each iteration of the model's work until we achieve the format we need.

🧐 3. Critique and Revision Prompting

Next level! Forcing AI to Criticize Itself 🕵️‍♂️

What it is:

The model evaluates the quality of its own response and suggests improvements.

When it's useful:

When you want to awaken critical thinking in the model 🧠

Prompt:

Write an essay on the importance of environmental awareness. Then evaluate and improve your text.

First response:

Environmental awareness is crucial for preserving nature and sustaining life on the planet. It is important to sort waste and conserve resources.

Critique of the Model:

Analyze the text, identify stylistic and grammatical errors, and correct them.

Revised Response:

Every day, we choose the future: recycling plastic, conserving water, supporting local producers. Environmental awareness is our contribution to a healthy planet.

In this way, we instruct the model to analyze and apply the corrections to the text. Sometimes, this can be very useful. This technique is actively used in creating agents. We will explore this in more detail next time.

🧩 4. RLHF (Reinforcement Learning from Human Feedback)

And finally, a technique for those who want to choose the best 🔥

What it is:

Creating several options → choosing the best one → improving it.

When useful:

When you want a truly perfect result 🌟

Prompt:

Provide 3 answer options to the question: Why is it important to preserve biodiversity?

Options:

1. Supporting Ecological Balance
2. Providing Food and Medicine for Humanity
3. Impact on Climate Stability

Feedback:

The third option seems the best! Add specific facts.

Improvement:

Biodiversity plays a central role in climate stability: forests absorb CO2, and oceans regulate temperature. The loss of species leads to ecological disasters.

This technique works when you have conducted some analysis yourself and more or less know what you want to achieve. ### 🎯 Results

Now you know:

How to give AI clear and precise feedback ✍️
How to refine results over several iterations 🔄
How to make the model self-evaluate its responses 🧐
How to select and improve the best options 🧩

Attention! The best results are achieved by combining different approaches. However, it should be noted that since the context size in models is not unlimited, they may eventually lose the initial requirements or reduce their importance. Therefore, when giving feedback, it is advisable to periodically clarify previous requirements.

📣 Try it yourself!

Write a simple prompt and:

Evaluate the result 🎯
Provide feedback 🤓
Ask the model to clarify or critique itself 🔍
Create several versions and choose the best one 🌟

PS:

Thank you, friends, for staying with me! I hope, as always, my article will be useful to you. I would be very grateful for your likes, comments, and support of the project - bel-geek.com !

Painless Vibe-Coding: A Complete Practical Guide from Real-Life Experience

Siarhei — Tue, 11 Nov 2025 19:07:11 +0000

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.

Logic, validation, states.
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:

Idea -> bolt.new (prototype) -> transfer to Cursor.
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.

About context and LLM

Siarhei — Wed, 05 Nov 2025 08:34:21 +0000

Hello! Folks!

We continue our series of articles about AI (Artificial Intelligence) and how to use it. Today's article will be more theoretical. We will try to figure out what models are, their types, how to use them, and what features they have.

I hope you find it interesting, so let's go!

And so, as usual (as it seemed in school), let's understand the concept of AI models.

Artificial Intelligence — It's Not Magic, It's Math on Steroids

When you hear "AI model," it might seem like we're talking about something like a robot that thinks like a human. But in reality, it's much simpler (and more complex at the same time). An AI model is a mathematical construct that has been trained on data to later predict, classify, or even generate new texts, images, or codes.

For example, if you use a translator, get recommendations on Spotify, or filter spam in your mail, there's one or more of these models at work. But it's important to understand: a model is not the algorithm itself, but the result of its application to data.

The process usually looks like this: you take an algorithm (e.g., gradient boosting, neural network, or SVM), "feed" it data, and get a model. This model can then independently make decisions, such as determining whether there's a cat in a photo or if it's just a fluffy blanket.

In this article, we'll delve deeper: how different models differ, why foundational models (like GPT, Claude, etc.) are needed, and why you can't make even a simple chatbot today without powerful GPUs.

How an AI Model "Remembers" Information: Vectors, Spaces, and Mathematical Magic

Okay, we already know that a model is the result of training on data. But a logical question arises: how does it store all this? Does it not store it like Google Docs?

No. An AI model remembers nothing "human-like." It doesn't know that a "cat" meows or that "pizza" is tasty. Instead, it envisions the world through vectors—mathematical objects consisting of sets of numbers. Roughly speaking, each word, image, request, or even concept is converted into a digital code—a set of values in a space with hundreds or thousands of dimensions.

🧠 Example:

"cat" = [0.12, -0.98, 3.45, …]

When a model "thinks" about the word "cat" (usually it creates vectors for entire expressions), it doesn't work with text but with its vector representation. The same goes for the words "dog," "fluffy," "purrs," etc.

(Vector visualization. Top left - vectors of texts about prompting. Bottom right - vectors of texts about the Belarusian language.)

Interestingly, vectors close in this multidimensional space represent concepts that are close in meaning. For example, if the vector "cat" is near "dog," it means the model has learned to see something common between them (animals, domestic, fluffy).

How Are Vectors Compared?

The model measures cosine similarity or Euclidean distance between vectors. Simply put, it calculates how "parallel" or "close" vectors are to each other. The smaller the distance or the larger the cosine, the stronger the connection between concepts.

For example, in large language models (LLM) like GPT:

"Minsk" + "Belarus" ≈ "Paris" + "France"
"Book" + "read" - "paper" ≈ "electronic"

And Why Is This Needed?

Everything, from understanding user questions to generating answers, happens through manipulating these vectors. If you write in chat: "suggest a movie like Inception," the model searches for the vector "Inception," finds its neighbors in the space (e.g., "Interstellar," "Tenet"), and based on this, generates a recommendation.

Not All AI Models Are the Same: How They Are Divided

The variety of models is impressive. You can find models that analyze maps or detect diseases from images.

Let's try to typify AI models.

Starting with the fact that models can be divided by the types of data they work with:

🧠 Language Models (LLM)

Work with text: understand, continue, analyze, generate.
Modern examples:

Qwen 3 — supports both dense and Mixture-of-Experts architectures.
Gemma 3 — compact, efficient, works even on 1 GPU.
DeepSeek-R1 — focuses on reasoning and logic.
LLaMA 3.3 / 4 — new open-source LLM.

👁 Visual Models (Computer Vision / Multimodal Vision)

Work with images: recognize, analyze, generate.

LLaMA 4 Vision — understands images and can answer questions based on visual context.
Gemma Vision — scalable visual model from Google.
DALL-E

🎤 Audio and Speech Models

For speech recognition, voice generation, emotions, etc.
(Currently, there are few open-source competitors to Whisper or VALL-E, but they are expected.)

🔀 Multimodal

Capable of processing multiple types of data: text + image, text + audio, etc.
For example, LLaMA 4 — combines a language model with the ability to analyze images and supports agents (more on them in future articles).

🧰 Models Can Also Be Divided by Functionality:

Task-specific models Finely tuned for a single task (e.g., SQL generation, automatic medical analysis).
General-purpose models Perform multiple tasks without specific adaptation. These include all modern flagship models: Qwen 3, LLaMA 3.3, Gemma 3, DeepSeek-R1.
Tool-augmented models Can use tools like calculators, search, databases, even other AIs. Example: GPT-4 Turbo with tools, LLaMA 4 Agents, DeepSeek Agent (based on R1).

🏋️ Models Can Be Divided by Size Based on the Number of Parameters They Support `(B - Billions)`:

Tiny / Small (0.6B – 4B parameters) — works on local devices.
Medium (7B – 14B) — requires GPU, works stably.
Large (30B – 70B) — for data centers or enthusiasts with clusters.
Ultra-large (100B – 700B+) — requires special equipment.

Let's Discuss Features of Models You Might Not Know.

🧠 A Model Is Not Human. It Remembers Nothing

One might think that if a model answers your questions taking into account previous ones, it "remembers" the conversation. But that's an illusion. In reality, a model is a mathematical function that has no memory in the human sense.

Context Is Where All Memory "Lives"

Every time you send a request to a model, a so-called context is transmitted with it—the text of previous conversations, documents, instructions. It's like giving a person a cheat sheet before asking something. And if the next request doesn't contain the previous text, the model "forgets" everything.

📌 The model doesn't store any information after responding. Everything it "knows" is what you provided at the current moment.

Why Is This Important?

Because it means the model cannot remember users, the context of the conversation, or events. The model only remembers the data it was trained on during training or fine-tuning. If it seems like it "remembers," it's not the model's merit but the system around it that:

stores context,
dynamically loads it,
or uses vector databases or other tools to retrieve needed information.

🧊 The Model Is "Frozen Math"

To simplify: a model is a function that converts input (request + context) into output (response). And that's it. There's no internal dynamics that change between calls. (In simpler models, you can notice that the same prompt will yield the same answer)

It's like a calculator: you enter 2 + 2 and get 4. If you want to get 4 again, you need to enter 2 + 2 again.

Everything related to "memory," "personal history," "recall," are architectural add-ons. For example, agents with "memory" work like this:

The entire dialogue is stored externally (in a database, file, or vector system).
For each new request, the agent retrieves relevant fragments from "memory."
It adds them to the context and only then passes everything to the model.

The model itself doesn't even "know" this text is from memory—for it, it's just another part of the input.

🙅‍♂️ Can a Model Learn During a Conversation?

No. A typical AI model (including GPT, Claude, LLaMA) doesn't change itself during operation. For it to "learn" something, retraining or fine-tuning must occur, and that's a separate process that doesn't happen during a chat.

Even if the model answers incorrectly 100 times, it will continue to do the same until you create a new model or change the context.

📏 Context Isn't Infinite: Why a Model Can't "Read Everything"

One of the most common user misconceptions about AI is the illusion that a model can work with "the whole book," "the whole database," or "a lot of documents at once." But that's not true. Models have a strict limit on the context size they can process at one time.

What Is Context in a Technical Sense?

Context is the entire set of information you provide to the model in one call: your request, instructions, documents, dialogue history, etc. It's not just "text" but a set of tokens—special units to which text is broken down for processing.

Example:

The word "cat" is 1 token.
The word "automobile" might contain 2-3 tokens.
The English "The quick brown fox jumps over the lazy dog." is 9 tokens.

How Many Tokens Can Modern Models "Hold"?

GPT-3.5 - 4,096 tokens
GPT-4 - 8,192 - 32,000 tokens
GPT-4o - up to 128,000 tokens
Claude 3 - up to 200,000 tokens
LLaMA 3 - usually - 8k - 32k tokens

128,000 tokens is about 300 pages of text. Seems like a lot? But it quickly runs out when you add, for example, technical documentation or code.

🧨 What Happens If You Provide Too Much?

The prompt won't fit—the model will refuse to process it or cut off part (usually the beginning) and some data will be lost.
If you supply overly long texts, important parts may be "pushed" out of visibility.
Lower accuracy—even if all information fits, the model can "get lost" in volume and miss important parts.

Why Not Just Make "Infinite Context"?

The problem is that all tokens are processed together—and the more there are, the:

more memory is required on the GPU (Processors that process data),
more time computation takes,
worse the attention (attention) works: the model "spreads out" and doesn't understand what to focus on.

How to Work with Large Data?

If the text doesn't fit into the context, there are solutions:

🔍 RAG (Retrieval-Augmented Generation) — selecting the most relevant pieces before each request
📚 Vector search — finding text similar in meaning
🪓 Splitting — you provide information in parts
🧠 Agent with memory — uses an external database to "recall" previous material

✨ Let's Summarize…

Phew! If you've read this far—you're almost an expert 😎
Let's briefly go over the main points again:

✅ An AI model isn't magic; it's math that has learned from data
✅ All a model's "knowledge" is not stored like human memory but in vectors
✅ The model doesn't remember you—all "memory" lives in context
✅ There are many different models: by data type, functionality, and size
✅ Context is limited—and that's not a bug, but a feature you need to work with
✅ "Teaching a model in conversation"—is still not quite reality

So, if it seems like AI "understands" or "remembers," remember that you're actually facing a very smart calculator, not a virtual Jan Bayan with amnesia 🙂

Create your first MCP server

Siarhei — Mon, 03 Nov 2025 09:45:20 +0000

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:

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

bun install
bun index.ts

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

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

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

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

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

🧩 Architecture in simple terms

How the server works:

An MCP server is created — it registers tools (echo, get_proverb_by_topic, get_weather).
An HTTP transport is added — MCP can receive and send requests via /mcp.
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.
Context — the headers (apikey, applicationid) are stored in storage so that the tools can use them.
Termination — on shutdown (SIGINT/SIGTERM) the server closes properly.

Key Implementation Details

The server architecture consists of three main components:

1. MCP Server & Transport

const mcp = new McpServer({ name: 'test-mcp', version: '0.1.0' });
const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined  // Stateless mode
});
mcp.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)

mcp.registerTool('echo', {
    title: 'Echo',
    description: 'Return the same text',
    inputSchema: { text: z.string() }
}, async ({ text }) => ({
    content: [{ type: 'text', text }]
}));

2. Proverbs Tool - Fetches Belarusian proverbs with filtering

mcp.registerTool('get_proverb_by_topic', {
    inputSchema: {
        topic: z.string().optional(),
        random: z.boolean().optional(),
        limit: z.number().int().positive().max(200).optional()
    }
}, async ({ topic, random, limit }) => {
    const data = await fetch(PROVERBS_URL).then(r => r.json());
    let items = data.map(d => d.message);

    // Filter by topic
    if (topic) {
        items = items.filter(m => m.toLowerCase().includes(topic.toLowerCase()));
    }

    // Random selection with Fisher-Yates shuffle
    if (random) {
        // ... shuffle logic
    }

    return { content: [{ type: 'text', text: items.join('\n') }] };
});

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

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

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:

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

{
  "mcpServers": {
    "test-mcp": {
      "type": "http",
      "url": "http://localhost:3002/mcp",
      "headers": {
        "apiKey": "API_KEY_1234567890",
        "applicationId": "APPLICATION_ID"
      }
    }
  }
}

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.

{
    "servers": {
        "test-mcp": {
            "type": "http",
            "url": "http://localhost:3002/mcp",
            "headers": {
                "apiKey": "API_KEY_1234567890",
                "applicationId": "APPLICATION_ID"
            }
        }
    }
}

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:

docker compose build --no-cache
docker 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:

FROM oven/bun:1 as base
WORKDIR /app

COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile --production

COPY . .

EXPOSE 3002

HEALTHCHECK --interval=30s --timeout=3s CMD \
  curl -f http://localhost:3002/healthz || exit 1

CMD ["bun", "index.ts"]

docker-compose.yml:

version: '3.8'

services:
  mcp-server:
    build: .
    container_name: mcp-server
    ports:
      - "3002:3002"
    environment:
      - NODE_ENV=production
    restart: unless-stopped

Useful Docker Commands:

# View logs
docker compose logs -f mcp-server

# Restart service
docker compose restart

# Stop and remove
docker compose down

# Rebuild and restart
docker 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:

import { z } from 'zod';
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

export function registerMyTools(mcp: McpServer) {
  mcp.registerTool(
    'my_tool',
    {
      title: 'my_tool',
      description: 'A simple tool that adds 2+2',
      inputSchema: { name: z.string() },
    },
    async ({ name }) => ({
      content: [{ type: 'text', text: `Hello, ${name}!` }],
    })
  );
}

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:

import { z } from 'zod';
import { Pool } from 'pg';

const pool = new Pool({ /* config */ });

export function registerDatabaseTools(mcp: McpServer) {
    mcp.registerTool('query_users', {
        description: 'Search users by name or email',
        inputSchema: {
            searchTerm: z.string().min(2),
            limit: z.number().int().max(100).default(10)
        }
    }, async ({ searchTerm, limit }) => {
        const result = await pool.query(
            'SELECT id, name, email FROM users WHERE name ILIKE $1 LIMIT $2',
            [`%${searchTerm}%`, limit]
        );

        return {
            content: [{
                type: 'text',
                text: result.rows.map(r => `${r.name} <${r.email}>`).join('\n')
            }]
        };
    });
}

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.

Reliable AI workflow with GitHub Copilot: complete guide with examples

Siarhei — Thu, 30 Oct 2025 07:34:46 +0000

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

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/agents/*.agent.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.

.github/
  copilot-instructions.md
  instructions/
    backend.instructions.md
    frontend.instructions.md
    actions.instructions.md
  prompts/
    implement-from-spec.prompt.md
    security-review.prompt.md
    refactor-slice.prompt.md
    test-gen.prompt.md
  agents/
    plan.agent.md
    frontend.agent.md
.vscode/
  mcp.json
docs/
  feature.spec.md
  project.context.md
  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/agents/*.agent.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:

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

Tips.

Keep points short.
Avoid generic phrases.
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:

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

Note.

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

3.3. Chat modes - `.github/agents/*.agent.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:

---
description: "Plan - analyze code/specs and propose a plan; read-only tools"
model: GPT-4o
tools:[ "search/codebase"]
---
In this mode:
- Produce a structured plan with risks and unknowns
- 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):

Open the Copilot Chat panel.
In the top bar, choose the desired chat mode from the dropdown (the list is built from .github/agents/*.agent.md + built-in modes).
The mode applies only to this thread. To change - select another or create a new thread with the desired mode.
Check the active mode in the header/panel of the conversation; the References will show the *.agent.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 *.agent.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)

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).

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).
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.
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.

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.
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).
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

---
mode: 'agent'
model: GPT-4o
tools: ['search/codebase']
description: 'Implement a feature from a spec'
---
Goal: Implement the feature described in @docs/feature.spec.md.

Steps:
1) Read @docs/feature.spec.md and produce a short implementation plan (bullets)
2) List files to add/modify with paths
3) Propose code patches as unified diff; ask before installing new deps
4) Generate minimal tests and run them (report results)

Validation gates:
- Build, tests, lint/typecheck must pass
- Output includes the final diff and a TODO list for anything deferred
- 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:

# Feature: Export report to CSV
Goal: Users can export the filtered table to CSV.
Acceptance criteria:
- "Export CSV" button on /reports
- Server generates file ≤ 5s for 10k rows
- Column order/headers match UI; locale-independent values
Edge cases: empty values, large numbers, special characters
Non-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:

{
  "servers": {
    "github-mcp": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp"
    }
  }
}

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)

Instructions: copilot-instructions + all *.instructions.md with applyTo that match current paths. A specific instruction is added to the common context.
Chat mode: restricts the toolset and (if needed) the model for the session.
Prompt frontmatter: has the highest priority; can limit tools and override the model.
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

{
  "servers": {
    "goman-mcp": {
      "type": "http",
      "url": "https://mcp.goman.live/mcp",
      "headers": {
        "apiKey": "<YOUR_API_KEY>",
        "applicationid": "<YOUR_APPLICATION_ID>"
      }
    }
  }
}

3.8.2. Repo/Path rules - enforce i18n by default

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

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

3.8.3. Chat mode - limited i18n tools

/.github/agents/i18n.agent.md

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

3.8.4. Prompt - scaffold component + keys in Goman

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

---
mode: 'agent'
model: GPT-4o
tools: ['files','goman-mcp:*']
description: 'Scaffold a React component with i18n keys synced to Goman'
---
Inputs: componentName, namespace (e.g., `ui.button`), path (e.g., `apps/web/src/components`)

Goal: Create a React component and ensure all user-visible strings use i18n keys stored in Goman.

Steps:
1) Plan the component structure and list all user-visible strings
2) For each string, propose a key under `${namespace}`; reuse if it exists
3) Using Goman MCP, create/update translations for languages: en, be, ru (values may be placeholders)
4) Generate the component using `t('<key>')` and export it; add a basic test
5) Output a Markdown table: key | en | be | ru | action(created/updated/reused)

Validation gates:
- No hardcoded literals in the produced .tsx
- Confirm Goman actions succeeded (report tool responses)
- Tests and typecheck pass

Example component code:

import { t } from '@/i18n';
import React from 'react';

type Props = { onClick?: () => void };

export function PrimaryButton({ onClick }: Props) {
  return (
    <button aria-label={t('ui.button.primary.aria')} onClick={onClick}>
      {t('ui.button.primary.label')}
    </button>
  );
}

3.8.5. Prompt - prune unused keys when removing components

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

---
mode: 'agent'
model: GPT-4o
tools: ['files','goman-mcp:*']
description: 'Find and prune unused localization keys in Goman after code deletions'
---
Inputs: pathOrDiff (e.g., a deleted component path or a PR number)

Goal: Detect keys that are no longer referenced in the codebase and remove them from Goman after confirmation.

Steps:
1) Compute the set of removed/renamed UI elements (scan git diff or provided paths)
2) Infer candidate keys by namespace (e.g., `ui.<component>.*`) and check code references
3) For keys with **zero** references, ask for confirmation and delete them via Goman MCP
4) Produce a Markdown table: key | status(kept/deleted) | reason | notes

Validation gates:
- Never delete keys that still have references
- Require explicit confirmation before deletion
- Provide a rollback list of deleted keys

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

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

---
mode: 'agent'
model: GPT-4o
tools: ['files','goman-mcp:*']
description: 'Sync new/changed i18n keys and check for missing translations'
---
Goal: Compare code references vs Goman and fill gaps.

Steps:
1) Scan code for `t('...')` keys under provided namespaces
2) For missing keys in Goman - create them (placeholder text ok)
3) For missing languages - create placeholders and report coverage
4) 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

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

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

copilot <<'EOF'
/security-review prNumber=123
EOF

C. Pass prompt file parameters

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

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

D. Run a prompt with safe tool permissions

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

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

copilot
# inside the session - ask to switch to the required mode and run the prompt
Use the i18n chat mode.
/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

copilot <<'EOF'
Please review these changes:
@apps/web/src/components/PrimaryButton.tsx
@docs/feature.spec.md
/security-review prNumber=123
EOF

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:

copilot --model GPT-4o <<'EOF'
/implement-from-spec
EOF

H. i18n cycle with Goman MCP (CHAT)

Run sequentially in a chat thread:

/i18n-component-scaffold componentName=PrimaryButton namespace=ui.button path=apps/web/src/components
/i18n-prune pathOrDiff=@last-diff
/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

Split sessions by phases: Plan → Implementation → Review/Tests. Each phase has its own Chat Mode.
Attach only necessary instructions: use path-specific *.instructions.md instead of dumping everything.
Project memory: record short ADRs in project.memory.md - this reduces agent "forgetting" between tasks.
Context helpers: keep frequent references (API/security/UI) in *.context.md and link to them from prompt files.
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.

# .github/workflows/ai-review.yml
name: AI Review (Copilot CLI)
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  ai_review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install Copilot CLI
        run: npm install -g @github/copilot
      - name: Run security review prompt (no dangerous tools)
        env:
          PR: ${{ github.event.pull_request.number }}
        run: |
          copilot -p "Run /security-review with prNumber=${PR}" \
            --deny-tool shell("rm*") --deny-tool shell("curl*") \
            --allow-tool shell("npm run test:*") \
            --allow-tool "github:*" \
            > ai-review.txt || true
      - name: Comment PR with results
        if: always()
        run: |
          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

Add .github/copilot-instructions.md (at least 5–8 bullets about build/tests/style).
Create 1–2 *.instructions.md with applyTo (frontend/backend or workflows).
Add plan.chatmode.md and one prompt (for example, implement-from-spec.prompt.md).
Create docs/feature.spec.md and docs/project.memory.md.
Include MCP (GitHub MCP at minimum) via .vscode/mcp.json.
Run the workflow in VS Code: /implement-from-spec - verify - PR.
(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

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

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

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

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

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

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

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

/.github/agents/plan.agent.md - custom chat mode

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

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

---
mode: 'agent'
model: GPT-4o
tools: ['search/codebase']
description: 'Perform a security review of a pull request'
---
Goal: Review PR ${input:prNumber} for common security issues.

Checklist:
- Authentication/authorization coverage
- Input validation and output encoding (XSS/SQLi)
- Secret management and configuration
- Dependency versions and known CVEs

Output:
- A Markdown table: issue | file | line | severity | fix
- If trivial, include a unified diff suggestion

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

---
mode: 'agent'
model: GPT-4o
tools: ['search/codebase']
description: 'Implement a feature from a spec'
---
Your task is to implement the feature described in @docs/feature.spec.md.

Steps:
1) Read @docs/feature.spec.md and summarize the plan
2) List files to add or modify
3) Propose code changes; ask before installing new dependencies
4) Generate minimal tests and run them

Validation gates:
- Build, tests, lint/typecheck must pass
- Provide a TODO list for anything deferred

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

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

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

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

/docs/feature.spec.md - spec skeleton

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

/.vscode/mcp.json - minimal MCP config

{
  "servers": {
    "github-mcp": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp"
    }
  }
}

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)

# Start an interactive session in your repo
copilot

# Allow/deny specific tools (exact flags per GitHub docs)
copilot --allow-tool "shell(npm run test:*)" --deny-tool "shell(rm*)"

# Run a prompt file non-interactively (example)
copilot <<'EOF'
/security-review prNumber=123
EOF

GitHub Actions - comment review results on a PR

name: AI Security Review (Copilot CLI)
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install Copilot CLI
        run: npm install -g @github/copilot
      - name: Run security review prompt
        env:
          PR: ${{ github.event.pull_request.number }}
        run: |
          copilot --allow-tool "shell(npm run test:*)" --deny-tool "shell(rm*)" <<'EOF'
          /security-review prNumber=${PR}
          EOF
      - name: Post results
        run: |
          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!

Overengineering in code: Programming for the Sake of Programming?

Siarhei — Fri, 23 Aug 2024 10:49:24 +0000

Recently, a situation in one of my pull requests made me reflect on the rationality of certain approaches in programming. My colleagues suggested removing comments from the code and splitting it into components. This made me think that sometimes code optimization turns into overengineering, which is the unnecessary complexity justified not by practical needs but by the ideals of "proper" code. Let’s delve deeper into this topic.

Example Code

Let’s consider a simple example of code:

<!-- Spinner -->
<div class="animate-spin rounded-full h-32 w-32 border-t-4 border-b-4 border-gray-300" />
<!-- Text -->
<div class="mt-8 text-center">
  Loading...
</div>

This code is straightforward: one part handles the spinner, and the other handles the text. The comments make it easy to understand what is happening. However, the suggestions for refactoring were as follows:

Remove comments.
Split the code into separate components.

Pros and Cons of Comments in Code

Arguments "for" Comments:

Simplifies code readability: Comments help quickly understand the purpose of code blocks without delving into implementation details.
Supports teamwork: In a team with varying levels of knowledge and experience, comments can be a valuable guide for new team members.
Reduces cognitive load: A quick glance at a comment allows the developer to focus on more important parts of the work without getting distracted by code analysis.

Arguments "against" Comments:

Redundancy: Code should be self-documenting, and if it requires comments to be understood, it may indicate that the code is not clear enough on its own.
Maintaining comments: Over time, comments can become outdated if not maintained along with the code, potentially misleading other developers.
Reduces readability: If there are too many comments, it can clutter the source file and detract from the overall readability.
Splitting into Components

Arguments "for" Components:

Reusability: Components allow code to be reused in other parts of the application, increasing efficiency.
Separation of concerns: Each component is responsible for a single function, making testing and maintenance easier.
Better code organization: Composing code from components often results in a cleaner, more modular architecture.

Arguments "against" Components:

Complexity: Excessive decomposition can add unnecessary complexity to a project, making navigation and understanding of the system harder.
Overengineering: Breaking even simple elements into components can turn into "programming for the sake of programming" without clear benefits for the final product.
Increased number of files: The more components there are, the more files are added to the project, complicating its structure and navigation.

My Opinion
Personally, I believe that using comments and keeping the code simple have their advantages, especially when the code is straightforward and easy to understand. In this example, comments serve as markers and help quickly grasp the purpose of code blocks. Splitting such code into separate components might lead to unnecessary complication.

That said, I acknowledge that each approach has its strengths, and depending on the project context, different practices might be beneficial. It’s essential to find a balance between maintainability and overcomplication.

Please share your thoughts on this. How do you balance simplicity and structure in your projects?