From b47b01d37954336cf9a630dc68b1419679693f32 Mon Sep 17 00:00:00 2001 From: kaivalya Date: Tue, 21 Jul 2026 20:24:43 +0200 Subject: [PATCH] New article --- .../content/blog/2026-06-20-ia_pourquoi.en.md | 38 ++++++++++++++ .../content/blog/2026-07-10-ia_methode.fr.md | 40 --------------- .../content/blog/2026-07-21-ia_methode.en.md | 50 +++++++++++++++++++ .../content/blog/2026-07-21-ia_methode.fr.md | 50 +++++++++++++++++++ 4 files changed, 138 insertions(+), 40 deletions(-) create mode 100644 website/content/blog/2026-06-20-ia_pourquoi.en.md delete mode 100644 website/content/blog/2026-07-10-ia_methode.fr.md create mode 100644 website/content/blog/2026-07-21-ia_methode.en.md create mode 100644 website/content/blog/2026-07-21-ia_methode.fr.md diff --git a/website/content/blog/2026-06-20-ia_pourquoi.en.md b/website/content/blog/2026-06-20-ia_pourquoi.en.md new file mode 100644 index 0000000..737efca --- /dev/null +++ b/website/content/blog/2026-06-20-ia_pourquoi.en.md @@ -0,0 +1,38 @@ +--- +title: "Why use AI" +date: 2026-06-20 +description: "Why I used AI so heavily to build TrainUs" +draft: true +--- + +I used AI _massively_ to build TrainUs. + +Given my background (a computer science engineer) and my professional experience (I worked as a developer), I have the technical skills needed to build this kind of application. My problem was never skills, or even ideas for an app: I've always had plenty of ideas for personal projects. My problems have always been **time and motivation**. + +Lastly, in my professional field, I need to learn how to use these kinds of tools, and doing so on personal projects allows for a lot more experimentation than at work. And let's be honest, it's also fun to try out these tools everyone's talking about. + +## Time + +A software project always takes more time than you think, and it often follows the Pareto principle: the first 80% of the project takes 20% of the time needed to do the whole thing, and the last 20% takes 80% of your time. That's often why POCs (Proof of Concepts) take so little time: they never do that last 20% — which is often the least interesting part anyway. + +## Motivation + +I already spend 8 hours a day in front of a screen, so I want to do something else with my free time. And while there's real pleasure in fixing a bug that's resisted you for hours, the code itself was never my goal: I've always been interested in the product behind it. I'm the lazy type when it comes to a product's architecture, but uncompromising when it comes to tests and documentation. + +Basically, I generally don't feel like writing code, I feel like creating something useful (at least for me). + +## The AI + +So, AI solves this equation. + +For **time**, it can work on its own while I do something else (like my workout). Careful, though! It's not always _free_ either: it represents a **mental load** (at least at times, for me, since I'm still holding its hand a bit). Plus, it's super efficient at handling the remaining 20%! Example: its CSS expertise lets it quickly fix small GUI glitches that would have taken you quite a while. + +For **motivation**, it lets you refine your ideas and turn them into a product you can actually try out. The creating part stays on your side. + +## The fun + +Okay, AI is a bit what everyone's talking about right now. THE big ongoing revolution. The thing that's going to change everything forever. So naturally, that makes you want to try it. + +Sure, reviewing generated code isn't exciting, and honestly I've done little of it. But sending a prompt and getting the new feature back within an hour max (TrainUs is still a small app) is genuinely pleasant. And once you know how to go about it, having it write complete documentation in several languages is, for a solo developer with very little free time, pretty impressive. + +Well, it's not perfect, but it's still quite a tool! I haven't fully explored it (if that's even possible), but it's super interesting, and yes, I do plan to keep using it. diff --git a/website/content/blog/2026-07-10-ia_methode.fr.md b/website/content/blog/2026-07-10-ia_methode.fr.md deleted file mode 100644 index ee5d79a..0000000 --- a/website/content/blog/2026-07-10-ia_methode.fr.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "Méthode utiliser avec l'IA" -date: 2026-06-19 -description: "Méthode utiliser avec l'IA" -draft: true ---- - -# La méthode - -Architecture -Stack technique -Spec fonctionnelle -Decision log -Tests -Daitaxis pour la doc - -## Les outils - -Extension github copilot sur VS Code -OpenCode -Claude Code -tokscale - -VS code -git - - -## Les modèles - -Claude Opus 4.6 -Claude Sonnet 4.6 -Claude Sonnet 5 -Claude Fable 5 -Qwen 3.6 Pro -MiMo v2.5 Pro - -Merci tokscale ! - -Coût: plus de 300$ sans abonnement -Moins de trois mois \ No newline at end of file diff --git a/website/content/blog/2026-07-21-ia_methode.en.md b/website/content/blog/2026-07-21-ia_methode.en.md new file mode 100644 index 0000000..fa7612d --- /dev/null +++ b/website/content/blog/2026-07-21-ia_methode.en.md @@ -0,0 +1,50 @@ +--- +title: "AI: the method" +date: 2026-07-21 +description: "How I worked with AI to build TrainUs: the method" +draft: true +--- + +In a [previous article]({{< relref "2026-06-20-ia_pourquoi.en.md" >}}), I explained _why_ I used AI so heavily to build TrainUs. Here, I'll talk about the _how_. + +Because yes, following a method helps! So I more or less adopted the usual method, really: a spec, a plan, rules (well, it's more explicit with an AI), tests (vital here), and docs (for me, for it, for contributors, and for users). + +## Architecture + +I told you I'm the lazy type when it comes to architecture, but let's be honest: the structuring decisions were mine, and made from the start. A 100% local, serverless app that works entirely offline: the data stays on the user's device, in a database embedded directly in the browser. No account, no cloud, no backend to maintain — and a workout that doesn't depend on the gym's Wi-Fi. + +Where I delegate is the detailed architecture: how components and composables are split, the data access layer, code organization. The AI proposes within a framework. At the root of the project, a rules file (`AGENTS.md`) that the AI reads every session: KISS, SOLID, DRY, minimal changes rather than big refactors. And above all: a step-by-step plan, validated by me **before** writing a single line of code, and manual validation between each step (well, I need to revisit that — I usually have little to object to, so I'm figuring out how to validate "less"). No "go ahead, build the whole app." One feature at a time. In fact, I often draft the text of my features ahead of my work sessions — offline mode ;-) . + +Some rules are non-negotiable and written in black and white. Example: "forbidden to bump the database schema version without asking me first," because otherwise it bumps the version on every DB change, except I've never actually shipped a release, so it's pointless. + +Sometimes the AI makes choices just to make things work that are unfortunate. Example: "if OPFS doesn't work, create the database in memory" — okay, that doesn't crash the app, but it shouldn't do that; it should tell the user the app doesn't work in their browser. + +## The tech stack + +The stack, to be precise, is a team effort — but nothing gets in without my approval, and the decision process varied from one piece to another. SQLite WASM directly in the browser, with data stored on OPFS (Origin Private File System): that one I imposed, it's what makes 100% local possible with real persistence. Vue 3? A joint decision. Vite and i18next? Proposals from the AI that I validated — I wanted multilingual support, it suggested i18next, adopted. And for Hugo on the website side, we did a proper comparative study… even though, I'll admit, I already had it in mind. + +Really, you have to decide what's non-negotiable, what's up for discussion, and what's exploratory (or no opinion). And once the stack is set and documented, the AI knows where it's going (and so do I). + +## The functional spec + +Everything starts from a written specification: what the app does, the two modes (edit and execution), the entities. From there, the AI derived a plan (`plan.md`) broken down into steps, each with its status and verification method. It's the project's steering document: I know what's done, what's waiting for my approval, what's left. And the AI keeps it up to date — that's part of its definition of "done." + +## The decision log + +Every technical decision is logged: the date, the decision, and above all the _why_ (what was considered and rejected). This is doubly useful with AI. From one session to the next, it remembers nothing: the log gives it context back and keeps it from re-proposing a solution already ruled out. And for me, when I come back three weeks later I can go read why we did that. Here too, the AI writes it up from our exchanges. + +## Tests + +My number one safety net. End-to-end tests with Playwright, on Firefox **and** Chromium, covering the green paths (the happy flow) and the red paths (bad inputs, edge cases, error states). A step isn't done until the tests pass on both browsers. + +That's what lets me get away with barely reviewing the generated code: if the full suite passes, the new feature is tested both ways, and my manual validation is OK, the regression risk is low. Without this test base, working this way would be reckless. + +## Diataxis for the docs + +User documentation follows the [Diataxis](https://diataxis.fr/) framework: a tutorial (quick start), how-to guides (how to do X), a reference (the user guide, screen by screen), and an explanation (understanding the concepts). All of it in English and French, plus a separate technical doc for developers. + +Let's be honest: on my own, with my free time, I would **never** have written all that. With AI, the docs get updated at every step — it's in the definition of "done," same as the tests. Giving it a known framework like Diataxis works really well: it knows exactly what type of content goes where, and the result is far more structured than a plain "write me some docs." + +## In short + +The method is pretty classic, really: a spec, a plan, rules, tests, docs. Nothing revolutionary — it's what we should be doing on any project. The difference is that AI makes the cost of this rigor nearly zero — and in return, that rigor is exactly what makes the AI reliable. The framework is what turns a code generator into a real teammate. Just watch out, though: it can get lazy too sometimes and forget the docs, the tests, or the decision log, so you still have to keep your eyes open and remind it (reminds me of certain people :-p ). diff --git a/website/content/blog/2026-07-21-ia_methode.fr.md b/website/content/blog/2026-07-21-ia_methode.fr.md new file mode 100644 index 0000000..c9d0549 --- /dev/null +++ b/website/content/blog/2026-07-21-ia_methode.fr.md @@ -0,0 +1,50 @@ +--- +title: "IA : la méthode" +date: 2026-07-21 +description: "Comment j'ai travaillé avec l'IA pour créer TrainUs : la méthode" +draft: true +--- + +Dans un [précédent article]({{< relref "2026-06-20-ia_pourquoi.fr.md" >}}), j'expliquais _pourquoi_ j'ai massivement utilisé l'IA pour créer TrainUs. Ici, je vais parler du _comment_. + +Parce que oui, suivre une méthode ça aide ! Du coup j'ai adopté peu ou prou la méthode habituelle en fait : une spec, un plan, des règles (bon ça s'est plus explicite avec une IA), des tests (vital ici) et de la doc (pour moi, pour elle, pour les contributeurs et pour les utilisateurs). + +## L'architecture + +Je vous ai dit que j'étais du genre feignant sur l'architecture, mais soyons honnêtes : les décisions structurantes, c'est moi qui les ai prises, et dès le départ. Une application 100 % locale, sans serveur, et qui fonctionne entièrement hors ligne : les données restent sur l'appareil de l'utilisateur, dans une base embarquée directement dans le navigateur. Pas de compte, pas de cloud, pas de backend à maintenir — et une séance qui ne dépend pas de la qualité du réseau dans la salle de sport. + +Là où je délègue, c'est l'architecture de détail : le découpage en composants et composables, la couche d'accès aux données, l'organisation du code. L'IA propose dans un cadre. À la racine du projet, un fichier de règles (`AGENTS.md`) que l'IA lit à chaque session : KISS, SOLID, DRY, changements minimaux plutôt que gros refactoring. Et surtout : un plan étape par étape, validé par moi **avant** d'écrire la moindre ligne de code, et une validation manuelle entre chaque étape (bon là faut que je revois, souvent j'ai peu de chose à redire donc à voir comment "moins" valider). Pas de "vas-y, fais toute l'appli". Une feature à la fois. D'ailleurs je prépare souvent le texte de mes features en amont de mes sessions de travail - en mode offline ;-) . + +Certaines règles sont non négociables et écrites noir sur blanc. Exemple : "interdiction d'incrémenter la version du schéma de la base de données sans me demander d'abord" parce que sinon à chaque changement de la DB elle incrémente la version sauf que j'ai jamais fait de release donc ça sert à rien. + +Parfois l'IA fait des choix pour que ça marche qui sont malheureux. Exemple: "si le système OPFS ne marche pas créer la base de données en mémoire", ok ça ne plante pas l'application mais il ne faut pas le faire, il faut dire à l'utilisateur que l'application ne marche pas sur son navigateur. + +## La stack technique + +La stack, soyons précis, c'est un travail d'équipe — mais rien n'y entre sans ma validation, et le mode de décision a varié d'une brique à l'autre. SQLite WASM directement dans le navigateur, avec les données stockées sur OPFS (Origin Private File System) : ça, je l'ai imposé, c'est ce qui rend le 100 % local possible avec une vraie persistance. Vue 3 ? Une co-décision. Vite et i18next ? Des propositions de l'IA que j'ai validées — je voulais du multilingue, elle m'a proposé i18next, adopté. Et pour Hugo côté site, on a fait une étude comparative dans les règles… même si, j'avoue, je l'avais déjà en tête. + +En fait il faut décider ce qui est non négociable, ce qui peut être discuté et ce qui est de l'ordre de l'exploratoire (ou sans avis). Et une fois la stack posée et documentée, l'IA sait où elle va (et moi aussi). + +## La spec fonctionnelle + +Tout part d'une spécification écrite : ce que fait l'appli, les deux modes (édition et exécution), les entités. De là, l'IA a dérivé un plan (`plan.md`) découpé en étapes, chacune avec son statut et sa méthode de vérification. C'est le document de pilotage du projet : je sais ce qui est fait, ce qui attend ma validation, ce qui reste. Et c'est l'IA qui le tient à jour — ça fait partie de sa définition de "terminé". + +## Le decision log + +Chaque décision technique est consignée dans un journal : la date, la décision, et surtout le _pourquoi_ (ce qui a été envisagé et rejeté). C'est doublement utile avec l'IA. D'une session à l'autre, elle ne se souvient de rien : le log lui redonne le contexte et lui évite de re-proposer une solution déjà écartée. Et pour moi, quand je reviens trois semaines plus tard je peux retourner lire pourquoi on a fait ça. Là encore, c'est l'IA qui rédige à partir de nos échanges. + +## Les tests + +Mon garde-fou numéro un. Des tests de bout en bout avec Playwright, sur Firefox **et** Chromium, qui couvrent les chemins verts (le flux nominal) et les chemins rouges (mauvaises saisies, cas limites, états d'erreur). Une étape n'est pas terminée tant que les tests ne passent pas sur les deux navigateurs. + +C'est ce qui me permet d'assumer de peu relire le code généré : si la suite complète passe, que la nouvelle feature est testée dans les deux sens et que ma validation manuelle est OK, le risque de régression est faible. Sans cette base de tests, travailler comme ça serait de l'inconscience. + +## Diataxis pour la doc + +La documentation utilisateur suit le cadre [Diataxis](https://diataxis.fr/) : un tutoriel (démarrage rapide), des guides pratiques (comment faire X), une référence (le guide utilisateur écran par écran) et une explication (comprendre les concepts). Le tout en anglais et en français, plus une doc technique séparée pour les développeurs. + +Soyons honnêtes : seul, avec mon temps libre, je n'aurais **jamais** écrit tout ça. Avec l'IA, la doc est mise à jour à chaque étape — c'est dans la définition de "terminé", au même titre que les tests. Donner un cadre connu comme Diataxis, ça marche très bien : elle sait exactement quel type de contenu va où, et le résultat est bien plus structuré qu'un "écris-moi de la doc". + +## Bref + +La méthode, c'est du classique en fait : une spec, un plan, des règles, des tests, de la doc. Rien de révolutionnaire, c'est ce qu'on devrait faire sur n'importe quel projet. La différence, c'est que l'IA rend le coût de cette rigueur quasi nul — et qu'en retour, cette rigueur est exactement ce qui rend l'IA fiable. Le cadre, c'est ce qui transforme un générateur de code en vrai coéquipier. Bon par contre attention elle peut devenir feignante elle aussi par moment et oublier la doc ou les tests ou le decision log donc faut quand même garder les yeux ouverts et le lui rappeler (ça me rappelle certaines personnes :-p ).