📖 Spec-Driven Development

Let’s talk more about agentic development. Several month ago I had a thought: the reason AI often produces poor code or software is not because it’s a bad programmer, but because we, the operators, fail to explain clearly enough what we want.

🧠 We need to consider the limitations of human cognition and the common context we share. When we say “I want a button” we already imagine it quite well (e.g., the one from your company’s UI kit), while AI only sees it as the fact that you want a button.

Then I came across this video, where the speaker explains that the new way of coding isn’t about using a better programming language or a better LLM, but about writing comprehensive specifications.

🤖 The other problem is that I don’t want to write long texts to AI. It feels boring, and I’m more productive when I’m typing code instead of text. Is there anything that can help me here? Yes — AI itself!

✨ Experiment

Last week GitHub released a tool called spec-kit (short video here). Essentially, it’s a workflow composed of several prompts. It forces you to first describe your product or feature, then the technologies you want to use. From there, it generates a specification. You can edit that spec as plain text. Once you’re satisfied, it generates tasks. Only then should you ask your agent to start development.

So instead of starting with “I want a button” you start with a rich specification of your product, its ecosystem, and your expectations. This way, the LLM understands you much better.

I quickly tried it and here are the results.

What I asked it to do:
* Generate an app where you select a background and add facts about yourself. It should place them on top of the background image.
* Use React.

I didn’t edit the spec much — just added one feature. It generated something that worked, though I later had to make ~10–15 updates with prompts outside the spec workflow. Still, I think it kept the specification in context while applying those changes. I also liked how seamlessly it integrated with GitHub Copilot.

Repo:
👉 https://github.com/PavelPolyakov/background-with-facts
(see the generated specifications here)

Result:
👉 https://background-with-facts.onrender.com

WDYT?

0️⃣1️⃣ Claude Shannon

I’m finishing a book called A Mind at Play: How Claude Shannon Invented the Information Age. Do you know who Claude Shannon is? Probably not. Yet the Claude LLM is named after him. Moreover, many people believe his name and discoveries should be mentioned alongside Einstein and Turing. So now you know — he was quite an important person, especially for both me and you!

Before Shannon, people were communicating, but they couldn’t articulate what “information” actually is. Why? Because they didn’t know how to measure it. Shannon thought this through: he proved that there is a smallest possible piece of information and gave it a name — the bit. Thanks to him, we can measure information, quantify how much can be sent through a given channel, reduce noise, and much more. All thanks to Claude Shannon.

But today, I want to share something practical from the book: ✨ six strategies Claude Shannon suggested for solving any problem.

1️⃣ Start with simplifying. Almost any problem has extra details you don’t need at the start. Focus on the core issue.

2️⃣ Encircle your problem with existing answers to similar questions. Then ask yourself: how can these answers help solve your current problem?

3️⃣ If you still can’t solve it — restate the question. How else can it be described? Try changing the viewpoint.

4️⃣ Break the problem into smaller pieces. Solve them one by one. It’s easier than tackling the whole thing at once.

5️⃣ Problems that can’t be analyzed can still be imagined. If you can’t prove your conclusion logically, assume it’s already true and see what follows. Do contradictions appear?

6️⃣ When you have an answer, stretch it. Can it be generalized further? Can its application be broader?

It’s clear you don’t need to be a scientist to use these strategies. They work just as well for IT problems.

And if you want to learn more about Claude Shannon, you don’t even need to read the book. There’s an excellent documentary on YouTube.

🤖 Force ChatGPT to use Python

Did you know that LLMs are often bad at math? When they try to calculate purely based on model weights, they can easily slip. The good thing is that modern models often try to detect when they should use proper tools for math. For ChatGPT, that tool is Python.

And you can do it yourself by simply adding “use python” to your prompt. ChatGPT will then write a noscript, execute it, and share the result. You can even check the noscript to verify the logic.

For example:

What shall be my running pace if I run 4 minutes, then walk 1 minute. So that I finish 10k in 55 minutes? use python

Pretty neat, right? But here’s something even cooler. Today I learned that ChatGPT can also use Python to plot simple charts — and that’s super handy.

For example:

Plot this to the chart:

Jan 2025    Running    13
Feb 2025    Running    12
Mar 2025    Running    13
Apr 2025    Running    13
May 2025    Running    13
Jun 2025    Running    13
Jul 2025    Running    12
Aug 2025    Running    11
Sep 2025    Running    9

use python

✨ Works like a charm.

Why is this important? Because when we share information with others, we should think about how to make it easier to consume. And people process charts much better than plain text. So it’s worth spending a minute to quickly wrap your data in a chart 📈.

🙎 Face Liveness Check

Recently, I worked on adopting a new technology, face liveness check, and I’d like to share my findings with you.

You probably know that many companies require their customers to go through a KYC (Know Your Customer) process. It used to be done via a video call, but now it’s mostly asynchronous and automated. Usually, you have to upload some form of ID and take a selfie. Of course, there are 🦹 bad actors who try to bypass verification without doing it properly (identity fraud). So the big question is: how can we reliably validate that there’s a real person in front of the camera?

It turns out there are not only solutions from specialized identity verification providers like Jumio or Onfido, but also a solution from AWS. And the best part — you can integrate it just like any other AWS service (S3, DynamoDB, etc.)! 🎥 Check out the demo. AWS checks if it’s a real human in front of the camera and returns a confidence score along with a reference image. They even claim it can detect high-quality rubber masks so fraudsters can’t trick the system this way. What I also found amusing is the 🌈 “rainbow dance” the UI makes you do — projecting colors on your face and analyzing the reflections. Honestly, it’s pretty awesome!

Another interesting part: AWS requires you to use their UI for this service. Yes, the UI can be extended, but it comes with some limitations. For example, they provide it only as a React component (+ use proprietary AWS Amplify setup). I had to integrate it into a Vue app, and to my surprise (I’m not really a front-end person), there’s already a way to do this! You can build your React app and then wrap it as a web component (see example).

Let’s say we call it face-liveness-ui. It will produce a face-liveness-ui.js file, which you can then include in any application and simply use as:

<face-liveness-ui></face-liveness-ui>

You can even pass parameters and listen for events, e.g.:

host.dispatchEvent(new CustomEvent("face-liveness-ui:success"));

The pricing is also quite low it costs less than 2 cents!

Pretty cool stuff ✨

🧹 Clean Your Mac (or not)

Recently on Twitter, I saw a mention of a CLI tool that promised to free up space on my Mac. Disk space is definitely one of my pain points. Even with 500 GB, I often get warnings that there’s no space left and that I need to delete something.

The tool is called Mole, and it’s open source on GitHub. There’s only one problem: security. I’m a little hesitant to run random CLI tools that have full access to my file system. With Mole, I had double doubts — it’s called “Mole,” and it comes from a developer in 🇨🇳China. That sounds a little suspicious, doesn’t it?

At first, I thought: if they were developing and distributing spyware, they would probably try to hide it better instead of being so straightforward. But we live in a meta-ironic world, and maybe they’re playing on a different level, so people like me end up installing “Mole from China” on their laptops themselves.

Anyway, I wanted to check it more carefully. I browsed the GitHub repo — it looked decent. People were submitting issues, and the maintainer was pushing updates. Still, I wanted to be sure, so I installed it via Homebrew, checked the source code, and even copy-pasted the bash noscripts into ChatGPT to review them. The LLM said they were fine 📈.

So I ran mo clean --dry-run. Everything went fine. Then I ran mo clean for real, and again there were no issues.
Overall, I recovered about 70 GB of space, and everything is still running smoothly.

I’d say I recommend this tool, it has a nice UX and works well. But in the end, it’s up to you whether you want to install Mole from China on your laptop 🙌.

🔄 What goes around, comes around

Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.

Do you know this quote? Well, it just happened to me.

When I joined car2go, one of the first tasks for our team was to introduce a new search. The old one was based on the shared database, essentially a complex SQL query. It worked, but there was a bigger problem: this setup blocked the introduction of microservices and new teams.

So we fixed it. We introduced Elasticsearch and built two Node.js + Fastify services: customer-search (for searching), customer-search-feeder (for listening to updates and feeding them into Elasticsearch).

I still remember the complications with upserts and message ordering. In the pre-GPT era, I hacked together a noscript in Painless to decide what needed to be updated or not. The first insight from that work? “Painless” is a misnomer. Writing in that noscripting language was quite painful, especially since you couldn’t test it in isolation.

What happened next? I moved on to another team, and customers-search (and its buddies) moved to a different one. Fast forward 8 years to October 2025: we’ve just learned that one of the many Free2move teams will be shut down, and we’ll take over their workload. And guess what was on their plate? … customer-search!

Now this service has come back to me. What surprised me most is that in all these years, it hasn’t changed much. It still runs as it was designed, and even that old Painless noscript is alive and doing its job.

Here’s the lesson: only good software becomes legacy software, because it works so well, nobody has a reason to replace it.

So yes, I’m kind of happy to take care of customers-search again.
And indeed — the person maintaining it now knows my address.

📋 Three Things

This week, I want to share three random things I found cool recently.

1️⃣ The first is an awesome scratchpad called Antinote. It costs $5 (the first week is free), and it’s worth it.

I believe you also sometimes need to copy chunks of text here and there and maybe do some small manipulations with it. What do you use for that purpose? I used to rely on Sublime Text, but Antinote is even more lightweight and comes with some great features built-in, no extra plugins needed.

2️⃣ I recently finished listening to the book Musicophilia by Oliver Sacks.

In this book, the author explores how music is integrated into our brains and stimulates us in different ways. #longstoryshort — it’s integrated a lot. One interesting point he mentions is that music can actually improve your work and help you stay focused. I often listen to something while working, and I agree, it really helps.

Recently, I discovered 🎵this track from the Succession TV series, and I love it. You should give it a try too.

3️⃣ Finally, there’s an awesome talk about the current state of space exploration from the perspective of the European Space Agency (ESA).

Yes, European — not NASA! It turns out that ESA is also doing a lot: amazing ongoing experiments and some super interesting plans for the future, all aimed at learning more about our universe. I highly recommend watching it, at least to understand what gravitational waves are and how incredible it is that we can now detect them (they literally bend spacetime!).

When you have something interesting to share too, feel free to drop it in the comments!

Hi everyone 💙💛

Once again, I’m joining a fundraising initiative organized by my friends from the volunteer organization @tazyky.ua. They have already delivered over 600 vehicles to the Armed Forces of Ukraine (AFU)! 🚙💪

This time, the team’s goal is to raise 666,000 UAH (yes, it’s our Halloween-themed fundraiser 🎃).
My personal goal is to collect 10,000 UAH, and I’d be incredibly grateful if you joined me in supporting this cause.

So far, I’ve raised about ~6,600 UAH and 80 EUR. We still need a few heroes to help me to close this campaign ✅

🚚 Why vehicles?
Vehicles are truly a consumable resource in wartime — they’re constantly on the move, often under fire, and play a crucial role in evacuations, logistics, and delivering aid and supplies to the front lines. Each new car literally helps save lives and bring victory closer.

Every small contribution counts and helps bring a fair peace to Ukraine and all of Europe. 🌍💪

🔗 Mono
https://send.monobank.ua/jar/AM8kbwYa8C

🇪🇺 Euro
https://www.paypal.com/paypalme/PavloPoliakov

Thank you so much for standing with us! 🙏💙💛

🤖 AI to Explain the Project

Here’s an interesting concept showing how AI can help us understand software better.

When you have a GitHub repository, you can replace the github part of the URL with deepwiki, and that tool will index your repository, generate detailed documentation, and even draw diagrams 📊.

Here’s an example using my small repo:
* Original: https://github.com/PavelPolyakov/grammy-with-tests
* DeepWiki version: https://deepwiki.com/PavelPolyakov/grammy-with-tests

The result looks quite good to me, though it was a small repository. On the DeepWiki homepage, you can also explore some popular repositories.

I believe this tool could be really helpful in situations like ours — when a team needs to maintain and support a workload that was developed elsewhere. Unfortunately, I can’t run DeepWiki against our corporate repositories 🤷.

💙💛
Now, back to the fundraising!

Thanks to everyone’s contributions, we’ve already raised 9,250 UAH and 155 EUR. It would be amazing to finish filling the Monobank jar today — let’s make it explode with your donations! Every hryvnia counts.

🔗 Monobank:
https://send.monobank.ua/jar/AM8kbwYa8C

🇪🇺 Euro (PayPal):
https://www.paypal.com/paypalme/PavloPoliakov

🙏,

⚙️ Tech Leadership Crash Course #4

I’m happy to announce that this year we are holding the 4th Tech Leadership Crash Course training.
It will take place in about one month, on December 4th, 6th and 8th.
This is a great opportunity to set yourself up for success in 2026.

During the course, we will learn and practice three core skills that every tech leader in any company and any domain should possess: Leadership, Hard Skills and Soft Skills.

You will not only learn something new, but more importantly, you will apply what you learn right away.
This hands-on approach helps the knowledge stick and allows you to use these new skills the very next day.
After the course, you will find yourself a confident tech leader who knows what to do and why.

The course is battle-tested, and participants from previous batches rated it as high as 9.5/10 📈.
Please also take a look at their feedback on the course landing page.

Our experience shows that the course content is useful both for people who want to learn more about tech leadership and for established tech leaders, who confirm they gain many insights during the training.

For people in this channel, we have a special discount code Good_dev_knows.
With it, the course will cost 20% less.

The course is held in 🇺🇦 Ukrainian.

🤝 Hope to see some of you in the course!

🇹🇳 Learn & Hack Tunisia 2025

I spent the whole last week in Tunisia. Yes, in Tunisia, Africa, and not as a tourist, but on a working trip. At the beginning of the year, I suggested to management that we organize technical training (like we used to have before; one that lasts several weeks where we only spend one or two days per week learning new stuff). But I got a counter-offer instead: What if we gather everyone for a week in 🇹🇳Tunisia (we have an office there) and, actually, create something?

So, I drafted a new concept, which I called "Learn & Hack Tunisia 2025." Gladly, it was supported, and we made it happen 📈. Here is what it was and what I learned.

Before you create a plan, you had better define what you want to achieve with it. Together with tech management, we defined three main goals:
🤝 build a community of tech leaders
💼 solve real business problems
🤖 leverage AI

To achieve that, we did the following. There were two main parts:💡 learn and 🛠 hack.

💡 The first three days started with the "Learn" part: tech leadership, hard skills, and soft skills—everything an established tech leader should know. Of course, it was backed up with exercises. This way, people tried the stuff they learned right away and absorbed the information much better.

🛠 The rest of the time was dedicated to the "Hack" part. We split the participants (about 20 people) into two end-to-end teams. Teams capable of delivering a feature from idea to real product. To do that, we combined different roles and mixed people from different teams and offices. During the hack part, teams worked on the same assignment, which we clearly defined before the training. During this week, the teams were supposed to develop an MVP and demo it to the audience on Friday.

🕺 And, of course, it wasn't only about learning and hacking. It was also about having fun. We had several activities and explored Tunis (the capital of Tunisia) together.

The results. The products which I saw exceeded my expectations. I was a little worried that teams had less than a full week to develop the product, but it turned out that in the current setup, that time is enough for a good MVP. Teams presented demos, and the feedback from both the jury and our tech department was super positive.

To me, the trip was a new experience as well:
1️⃣ Doing my Tech Leadership course in English in front of a live audience. It was a challenge, but also an opportunity.
2️⃣ Organizing such a big offline event. This was also a new thing for me. Even with the good support of management, HR, and the local office, and with positive feedback from participants, I still see things that could be improved in the next iteration.
3️⃣ The energy levels. The event itself was more exhausting than I expected :) It was, of course, fun and entertaining, but after years of remote work, socializing 16/7 feels different now.

In the next post, I’ll share more specific learnings from the training. Stay tuned.

🇹🇳 L&H Tunisia 2025: Insights #1

Let's continue with the Tunisia topic. As I mentioned in the previous post, the entire last week was dedicated to technical training in Tunisia, which I co-organized and also led. I'd now like to share what I learned from that experience.

🇹🇳 Tunisia

The first topic is the country and culture itself.

1️⃣ We received tremendous support from our local office in organizing the on-site training. And it truly helped. All of our colleagues were very friendly and willing to assist. That felt great.
2️⃣ It seems they have a cultural tradition of having coffee, tea, or drinks at 4:00 PM. Therefore, some snacks and drinks are delivered to the office each day, and people chat and eat a little. What a great tradition!
3️⃣ GDP per capita in Tunisia is even lower than in Ukraine, and you can see it on the streets. While the food (restaurants) is cheap and tasty (€4 for a tuna salad + local cola), the surroundings look less appealing. Just as I used to experience in Ukraine, you can relatively cheaply build something nice inside (a restaurant), but you cannot influence the outside much (the streets). Also, as we were told by locals, they think that Tunisians only build but do not spend enough resources on maintenance.
4️⃣ Experiencing plastic straws, water bottle caps you can detach from the bottle, or even a pack of cigarettes without pictures of dead people was a cultural shock for a European homebody like me. But the spirit of freedom was in the air!
5️⃣ It appeared that Tunis has it's own Santorini. Sidi Bou Saïd (on the attached image) looks and feels great and is just in 20 minutes from the city itself.

💡 Learning Part

As I said, I delivered my tech leadership course to my colleagues. 3 days, ~3 hours a day.

1️⃣ Location matters. For our first day, we had a hotel conference room arranged. And it felt great, like a real, high-end training. For the next two days, we used our office facilities, and since there was no conference room for ~20 people, we just used a kind of hallway. There was enough space, but a good location makes a huge difference.
2️⃣ Offline vs. Online. On one hand, offline was beneficial since people were engaged; it was easier to start interaction, and discussions sparked more naturally. On the other hand, I'm used to doing exercises on a Miro board, which provides a certain framing and space for all participants. Offline exercises were different, even if I adapted them a little.
3️⃣ Same Company vs. Mixed Group. I felt that since we had people from within the same company, it was a little more difficult for them to share some of their personal stuff with the group (such as sharing their personal goals). With a mixed group (different companies, as in the online training), it's easier for people to share since they feel more detached from the group.
4️⃣ It was great to see that some of the topics we had covered were used right away. For example, the presentation framework was applied to the team's demo presentation, which made it clear for non-technical people.

➡️ tomorrow I will finish with the hackathon summary and overall conclusion.

🇹🇳 L&H Tunisia 2025: Insights #2

Final part of my Tunisian tald. Let's talk about the product creation and my conclusions.

🛠 Hack Part

About two weeks before the event, I shared a PDF document with the assignment with the teams. We defined one task, described how it would be evaluated, and teams were expected to deliver an MVP within that week. The topic of our assignment was the following: imagine how Free2move may utilise ChatGPT Apps to improve our customer's experience.

1️⃣ When we were planning this event, I thought the teams would self-organize before the on-site part and maybe even start working on the assignment, as it would give them more time to achieve a better result. It turned out that it didn't happen the way I expected. And that is fine; it confirms my observation from the AI hackathon: people are different, and there is no reason to expect proactive behavior regarding the working topic from all of them.
2️⃣ Time. On the third day, when we happened to have a long lunch and were back to the office only at 4:00 PM, I thought that maybe, actually, there wasn't that much time left for the hackathon part, and teams wouldn't be able to produce anything solid. In the end, according to the plan, we only had four half-day slots plus one full day. But, to my surprise, even that amount of time was enough, and the demos were great.
3️⃣ There is a reason why teams achieved so much in such a short time: ✨ Vibe coding. I heard that helped a lot, especially because teams knew they were developing a one-off solution and it was not expected to be maintained in this form in the future. The solutions that were presented impressed everyone: the jury, the public, and me. They were exactly enough to demonstrate how the technology from the assignment could be applied and how Free2move could benefit from it. I confirm that ✨ Vibe coding rightfully got the word of the year award.
4️⃣ Before we gave out the assignment I checked myself that it's already possible to develop the ChatGPT Apps from Europe ✅ However, participants shared that the thing still feels quite raw. During the hackathon there was even a period of about 4 hours, where the app infrastructure of OpenAI was down. Nevertheless, it's interesting to explore new horizons and imagine how this new potential market might be integrated to the Free2move ecosystem. The attached image is just a mock-up to illustrate what it might look like.

🫡 Let's Summarize

The event was a success, both for the company and the participants. For me, the most important part was to bring people together and mix them in a way that made them more familiar with each other and therefore closer. This helps in different ways: people learn more about the different domains of our company, people meet new faces, and it's easier for them to work together in the future, and people learn from each other.

I think such events are powerful multipliers that keep the company velocity high. When you are a technical leader or want to establish yourself this way, consider the offsite event or training as one of the tools in your arsenal.

Technical leadership crash-course #4

Good news ⚡️If you want to boost your career and knowledge by taking the course I mentioned above, but for some reason you don’t want to apply to Free2move or travel to 🇹🇳 Tunisia, there’s a solution!

In just one week, on 04.12, my friends at fwdays and I are launching the fourth batch of our Tech Leadership crash course. It lasts only three days, but you’ll get hands-on experience performing the role of a technical leader — and the confidence that comes with it.

Here are just some of the reviews from past participants:

Коли ви думаєте що все знаєте про лідерство, архітектуру, презентації і зустрічі, то ви точно помиляєтесь. Цей курс звернув мою увагу на більш глибоке вивчення вказаних вище тем. Практична частина підібрано вдало і дозволяє краще закріпити матеріал.

Цей курс це значний поштовх на шляху до того щоб стати лідом. Він концентрує в собі корсну інформацію, на самостійний пошук та розуміння якої потрібен час. Кому це буде корисно на мою думку? Перш за все, цей курс буде корисний для розробників, що зараз фокусуються лише на потребах власної команди та власного проєкту, але бажають рухатися вперед та росповсюджувати свій вплив. Також цей курс буде цікавий для амбіційних людей, що впевнені у своїх лідерських якостях, але ще не мають необхідних навичок для того щоб взяти на себе роль ліда.

Дуже гарний, структурований і зрозумілий курс. Павло дуже добре і докладно все пояснює, приділяє увагу всім студентам і приділяє багато уваги на відповіді на питання. Практичні завдання дуже доречні і допомагають краще засвоїти матеріал. Так як це Crash course матеріал подається у стислому вигляді але є дуже багато рекомендацій по книгах від Павла де можна більш детально ознайомитись.

You can read more about the program on the website.
There are only a few tickets left, and the course starts next week. With the code Good_dev_knows, you can get a 20% discount.

👋,

📹 Interesting talk on how the ROI on the AI adoption might be measured in tech companies.

💡My insights

1️⃣ AI can lead up to 25% increase in productivity (10% median)

2️⃣ AI works best if your workload is following the best SE practices (tests, modularity, types)

3️⃣ You can measure AI adoption effect just using the git history and comparing past vs present

4️⃣ They provided example of one company of our size, after AI adoption
* number of PR grew up 📈 , but code quality decreased 📉
* Rework type of code changes increased x2.6 (a lot)
* Effective output gain only +1% 🤯

What does it all mean? 🤔

It does not mean that we will stop using AI, but that we will use it more consciously and improve in the areas where we are lagging. The fact that code is now cheaper is not the final answer. We have gained a new tool, and this tool helps (as proven by +25%), but achieving those +25% (or even +10%) is not a default outcome.

Hi friends ☀️,

I want to start this year (it’s already the 21st, huh?) with a bold move!

Over the year(s) of posting here in English, I’ve noticed a few things:
1️⃣ You are awesome, because you’re still here and reading my content
2️⃣ I like creating content and sharing my findings and conclusions
3️⃣ This channel is slowly dying

Before 2022, I ran this channel in Russian. After the full-scale invasion, I realized that there was no point for me in promoting Russian culture publicly by using the Russian language, so I switched the channel to English. It worked. Somehow. But it’s been working worse and worse over time. I don’t see the level of engagement I’d need to continue posting in English. Apparently, Telegram is not the best place to organically grow an English-speaking community, unless you’re a crypto bro.

However, as I already said, ✨ you are awesome ✨. I believe there are enough people here who understand 🇺🇦 Ukrainian, and I want to continue building a Ukrainian community of people who treat both life and tech consciously. I suspect that using 🇺🇦 Ukrainian will make it easier both for people to consume and engage with the content, and for me to find more people who are interested in it.

I’ve created a new channel: https://news.1rj.ru/str/LifeByPavloPoliakov, and I’d like to invite you to join 💪
There’s already a fresh post waiting for you!

There, I’ll write about tech, technical leadership, and not only that. About things that are important to me and that might be useful for you. For now, I plan to post there twice a week, and we’ll see how it goes!

For subscribers of this channel who don’t understand 🇺🇦 Ukrainian: thank you for being with me! This channel won’t be deleted, and from time to time I might still post here as well.

🤝,