Kodrudder, par lui-même

Kodrudder transforme une idée en une phrase en un dossier « ready-to-dev » (cadrage, règles, parcours, architecture, SQL, API, tâches) destiné à Cursor, Claude Code, Lovable ou Bolt. Chaque information y est marquée Fait (avec URL) ou H.

Ce qui est décidé

• Lot 1 : générer (Rapide ou Complète), discuter par section, exporter (ZIP + AGENTS.md), payer.
• Plans : gratuit (1 projet, Rapide, BYOK) et Solo à 15 €/mois (quota mensuel, BYOK au-delà).
• Export : AGENTS.md plus un CLAUDE.md d'une ligne qui l'importe.
• Stripe avec Stripe Tax ; base et stockage hébergés dans l'UE ; interface FR/EN.
• Hors lot 1 : GitHub, MCP, mises à jour par différences, agent de codage, équipes.

Ce qui reste une hypothèse à vérifier avant de coder

• Estimation coût/durée (D-02) : tester le ratio estimé/réel sur quelques idées types.
• Marge de Solo (15 €) : chiffrer le coût moyen d'une Complète avant de fixer les quotas.
• TVA/TTC et sorties hors UE vers les fournisseurs IA : validation juridique (DPA, base légale).

Corrections de la relecture

Ces corrections prévalent sur le texte des sections.

• EC-01 : RM-15 : plan free = 3 Rapides au total ; free_quota_used +1 par génération (transaction, verrou sur subscriptions), restitué si annulée sans section ou échec.
• EC-02 : le quota Solo se décompte par utilisateur sur quota_units (hors générations remboursées ou échouées) depuis current_period_start ; plafond 30.
• EC-03 : une génération BYOK a quota_units = 0.
• EC-04 : un job (ou évaluation à la lecture) bascule en free après grace_ends_at ou current_period_end.
• EC-05 : après DELETE /me, connexion refusée ; purge des données à J+30.
• EC-06 : ajouter GET /models et users.default_model_id.
• EC-07 : valider les questions en transaction (3 à 5, 2 options) avant insertion ; sinon relance puis failed.
• EC-08 : ajouter users.doc_locale_default.
• EC-09 : le SQL exporté est extrait des blocs de code de la section « Architecture et données ».

Comment utiliser ce dossier

1. Donner à l'outil de codage AGENTS.md (ou CLAUDE.md) et cette page, puis lui faire lire le Cadrage et les règles métier.
2. Lui fournir ensuite l'architecture, le SQL et l'API, en lui imposant les corrections ci-dessus.
3. Exécuter les tâches du plan dans l'ordre (T-01, T-02…), une par une, en validant chaque « preuve de fin » avant la suivante.

Résumé produit

• Kodrudder est un SaaS qui transforme une idée en une phrase en un dossier « ready-to-dev » unique. Il est destiné à Cursor, Claude Code, Lovable et Bolt.
• Le flux : 3 à 5 questions à deux options, puis génération (cadrage, règles, parcours, architecture, SQL, API, tâches). Chaque information est marquée « fait sourcé » ou « hypothèse ».
• Lot 1 : générer, discuter section par section, exporter (ZIP + AGENTS.md), payer. Données hébergées dans l'UE, interface FR/EN.

Utilisateurs et résultat attendu

Décisions tranchées

Périmètre MVP (lot 1)

Hors périmètre

Mesures de succès (H : cibles à calibrer après 30 jours)

Statuts (liste unique)

Besoins fonctionnels

Règles métier

Table de décision : autorisation de lancer une génération (RM-02, 03, 04, 09, 13)

Critères d'acceptation

Questions ouvertes (H à valider)

Parcours principaux

P-01 — Vibecoder / développeur : de l'idée au dossier exporté (U-01, U-02)

1. S'inscrire ou se connecter (e-mail + mot de passe, ou lien magique).
2. Saisir l'idée en une phrase et valider (≥ 10 caractères, RM-01).
3. Répondre aux 3 à 5 questions à deux options, une par une.
4. Choisir la profondeur (Rapide / Complète) et le modèle ; lire coût et durée estimés.
5. Accepter l'avertissement UE (1ʳᵉ génération), puis confirmer le lancement.
6. Suivre la progression section par section ; annuler possible.
7. Lire le dossier : sections 1 à 7, marqueurs Fait (URL) / H.
8. Discuter d'une section avec l'IA, puis « Appliquer » ou « Rejeter ».
9. Exporter le ZIP (AGENTS.md inclus).

P-02 — Clé BYOK et choix du modèle (U-02)

1. Ouvrir Réglages > Clés d'API.
2. Choisir le fournisseur, coller la clé, enregistrer.
3. Voir le résultat du test (valid / invalid) ; révoquer possible.
4. Sélectionner le modèle au moment du lancement ; voir la mention « indicatif ».

P-03 — Abonnement Solo (U-01, U-02)

1. Atteindre une limite (2ᵉ projet, Complète, quota) ou ouvrir Abonnement.
2. Consulter la comparaison Gratuit / Solo (15 €/mois).
3. Payer via Stripe Checkout, puis retour sur l'app avec statut mis à jour.
4. Gérer ou résilier via le portail Stripe.

P-04 — Suppression de compte (RGPD)

1. Réglages > Compte > Supprimer.
2. Si solo_active : résilier d'abord (RM-14).
3. Confirmer en saisissant « SUPPRIMER » ; message de purge sous 30 jours.

Écrans

Règles d'accessibilité et mobile

1. Clavier : tout parcours P-01 réalisable sans souris ; ordre de focus logique, focus visible, aucun piège (WCAG 2.2, https://www.w3.org/WAI/WCAG22/quickref/).
2. Erreurs et états : message textuel associé au champ, annoncé aux lecteurs d'écran ; la couleur ne porte jamais seule l'information, y compris pour Fait / H (texte ou icône + libellé).
3. Progression asynchrone : le suivi de génération (EC-06) annonce les changements de statut via une région live (H : aria-live="polite").
4. Cibles tactiles : ≥ 44 × 44 px H pour options du questionnaire et boutons de confirmation.
5. Mobile first : EC-03 à EC-06 utilisables à 360 px de large ; le chat (EC-08) s'ouvre en plein écran sur mobile, en panneau latéral sur desktop H.
6. Actions destructrices et coûteuses : confirmation explicite (lancement, annulation, suppression) ; libellés FR/EN sans texte codé en dur dans les images.

Limite : ces règles sont des exigences de conception ; la conformité WCAG reste à tester sur le rendu final (H : niveau AA visé).

Stack retenue

Composants

• Web : interface FR/EN, parcours idée → questions → estimation → dossier → export.
• API : authentification, projets, génération, chat, clés, export, webhooks Stripe.
• Worker : exécute les générations (queued → running), enregistre les sections, applique RM-06/07.
• Connecteur IA : appelle les modèles choisis, plateforme ou BYOK.
• Facturation : synchronise l'abonnement local depuis les webhooks (idempotents).
• Moteur de quotas : calcule le décompte (Complète = 3 Rapides, RM-03).

Modèle de données (PostgreSQL)

CREATE EXTENSION IF NOT EXISTS pgcrypto;

CREATE TABLE users (
  id            uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  email         text NOT NULL,
  password_hash text,                                   -- NULL si lien magique uniquement
  ui_locale     text NOT NULL DEFAULT 'fr' CHECK (ui_locale IN ('fr','en')),   -- BE-11
  eu_notice_accepted_at timestamptz,                    -- RM-13 : NULL = génération bloquée
  deletion_requested_at timestamptz,                    -- RM-14
  created_at    timestamptz NOT NULL DEFAULT now()
);
CREATE UNIQUE INDEX users_email_uq ON users (lower(email));

CREATE TABLE subscriptions (
  id                     uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id                uuid NOT NULL UNIQUE REFERENCES users(id) ON DELETE CASCADE,
  status                 text NOT NULL DEFAULT 'free'
    CHECK (status IN ('free','solo_active','solo_past_due','solo_canceled')),
  stripe_customer_id     text UNIQUE,
  stripe_subscription_id text UNIQUE,
  current_period_start   timestamptz,                   -- RM-03 : date anniversaire
  current_period_end     timestamptz,                   -- RM-12 : accès jusqu'à la fin de période
  grace_ends_at          timestamptz,                   -- RM-12 : 7 jours après impayé
  free_quota_used        integer NOT NULL DEFAULT 0
    CHECK (free_quota_used BETWEEN 0 AND 3),            -- RM-02 : 3 Rapides gratuites (H)
  updated_at             timestamptz NOT NULL DEFAULT now()
);

-- RM-12 : idempotence des webhooks Stripe (CA-24)
CREATE TABLE stripe_events (
  event_id     text PRIMARY KEY,
  type         text NOT NULL,
  processed_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE ai_models (
  id          text PRIMARY KEY,                         -- ex. identifiant catalogue
  provider    text NOT NULL,
  label       text NOT NULL,
  input_price_per_mtok  numeric(10,4) NOT NULL CHECK (input_price_per_mtok >= 0),
  output_price_per_mtok numeric(10,4) NOT NULL CHECK (output_price_per_mtok >= 0),
  active      boolean NOT NULL DEFAULT true
);

CREATE TABLE byok_keys (
  id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id     uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  provider    text NOT NULL,
  key_cipher  bytea NOT NULL,                           -- RM-09 : chiffré, jamais renvoyé ni journalisé
  key_last4   text NOT NULL,                            -- seul élément affichable
  status      text NOT NULL DEFAULT 'valid'
    CHECK (status IN ('valid','invalid','revoked')),
  created_at  timestamptz NOT NULL DEFAULT now(),
  UNIQUE (user_id, provider)
);

CREATE TABLE projects (
  id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  owner_id    uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,   -- RM-11
  name        text NOT NULL,
  idea        text NOT NULL CHECK (char_length(btrim(idea)) >= 10),   -- RM-01 : idée >= 10 car.
  doc_locale  text NOT NULL DEFAULT 'fr' CHECK (doc_locale IN ('fr','en')),  -- D-09
  status      text NOT NULL DEFAULT 'draft'
    CHECK (status IN ('draft','questioning','ready','generating','generated','failed')),
  created_at  timestamptz NOT NULL DEFAULT now(),
  updated_at  timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX projects_owner_idx ON projects (owner_id, created_at DESC);

CREATE TABLE questions (
  id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  project_id  uuid NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
  position    smallint NOT NULL CHECK (position BETWEEN 1 AND 5),    -- RM-01 : 3 à 5 questions
  prompt      text NOT NULL,
  option_a    text NOT NULL,                            -- RM-01 : exactement 2 options (deux colonnes NOT NULL)
  option_b    text NOT NULL,
  answer      text CHECK (answer IN ('a','b')),
  UNIQUE (project_id, position),
  CHECK (option_a <> option_b)
);
-- Le minimum de 3 questions est vérifié par l'application avant le passage en `questioning`.

CREATE TABLE generations (
  id               uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  project_id       uuid NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
  depth            text NOT NULL CHECK (depth IN ('rapide','complete')),
  model_id         text NOT NULL REFERENCES ai_models(id),
  key_source       text NOT NULL CHECK (key_source IN ('platform','byok')),
  byok_key_id      uuid REFERENCES byok_keys(id) ON DELETE SET NULL,
  status           text NOT NULL DEFAULT 'queued'
    CHECK (status IN ('queued','running','succeeded','failed','canceled')),
  idempotency_key  text NOT NULL,                       -- RM-05
  estimate_min_eur numeric(8,2) NOT NULL,               -- RM-04 : estimation obligatoire
  estimate_max_eur numeric(8,2) NOT NULL,
  estimate_min_sec integer NOT NULL,
  estimate_max_sec integer NOT NULL,
  estimate_confirmed_at timestamptz NOT NULL,           -- RM-04 : pas de génération sans confirmation (CA-09)
  quota_units      smallint NOT NULL CHECK (quota_units IN (0,1,3)),     -- RM-03 : Rapide=1, Complète=3
  quota_refunded   boolean NOT NULL DEFAULT false,      -- RM-06 : crédit restitué
  attempts         smallint NOT NULL DEFAULT 0 CHECK (attempts <= 2),    -- RM-06 : 2 tentatives
  error_message    text,
  created_at       timestamptz NOT NULL DEFAULT now(),
  finished_at      timestamptz,
  CHECK (key_source = 'platform' OR byok_key_id IS NOT NULL),
  CHECK (estimate_min_eur <= estimate_max_eur AND estimate_min_sec <= estimate_max_sec),
  UNIQUE (project_id, idempotency_key)
);
-- RM-05 : une seule génération queued/running par projet (CA-10 -> 409)
CREATE UNIQUE INDEX generations_one_active_uq
  ON generations (project_id) WHERE status IN ('queued','running');
-- RM-03 : décompte mensuel par utilisateur via project -> owner
CREATE INDEX generations_project_created_idx ON generations (project_id, created_at DESC);

CREATE TABLE sections (
  id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  project_id  uuid NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
  position    smallint NOT NULL CHECK (position BETWEEN 1 AND 7),    -- 7 sections du dossier
  slug        text NOT NULL,
  title       text NOT NULL,
  content_md  text NOT NULL,
  version     integer NOT NULL DEFAULT 1,               -- RM-08 : version courante
  generation_id uuid REFERENCES generations(id) ON DELETE SET NULL,  -- RM-06 : reprise à la 1re manquante
  updated_at  timestamptz NOT NULL DEFAULT now(),
  UNIQUE (project_id, position),
  UNIQUE (project_id, slug)
);

-- RM-08 : version précédente restaurable (CA-16)
CREATE TABLE section_versions (
  id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  section_id  uuid NOT NULL REFERENCES sections(id) ON DELETE CASCADE,
  version     integer NOT NULL,
  content_md  text NOT NULL,
  created_at  timestamptz NOT NULL DEFAULT now(),
  UNIQUE (section_id, version)
);

-- RM-07 : toute information porte un marqueur ; un Fait exige une URL (CA-13, CA-14)
CREATE TABLE claims (
  id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  section_id  uuid NOT NULL REFERENCES sections(id) ON DELETE CASCADE,
  text        text NOT NULL,
  kind        text NOT NULL CHECK (kind IN ('fact','hypothesis')),
  source_url  text,
  CHECK (kind = 'hypothesis' OR (source_url IS NOT NULL AND source_url ~ '^https?://'))
);
CREATE INDEX claims_section_idx ON claims (section_id);

CREATE TABLE chat_messages (
  id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  section_id  uuid NOT NULL REFERENCES sections(id) ON DELETE CASCADE,   -- RM-08 : chat par section
  role        text NOT NULL CHECK (role IN ('user','assistant')),
  content     text NOT NULL,
  proposal_md text,                                     -- proposition de l'IA
  proposal_status text CHECK (proposal_status IN ('pending','applied','rejected')),  -- appliquée seulement après acceptation
  created_at  timestamptz NOT NULL DEFAULT now(),
  CHECK (proposal_md IS NOT NULL OR proposal_status IS NULL)
);
CREATE INDEX chat_messages_section_idx ON chat_messages (section_id, created_at);

-- RM-02 : 1 projet actif maximum en free : contrôle applicatif en transaction
-- (verrou sur subscriptions) car la règle dépend du plan, non exprimable en contrainte simple.

Notes de cohérence

• Statuts alignés sur la section 2 : projet, génération, abonnement, clé BYOK.
• Hypothèses H : quota gratuit de 3 Rapides et grâce de 7 jours (Q-01, Q-02) ; dates anniversaire dérivées de current_period_start.
• Les règles RM-02 (limite de projets), RM-13 (avertissement UE) et RM-14 (purge sous 30 jours via deletion_requested_at et un job planifié) sont appliquées côté application ; les contraintes SQL couvrent les autres invariants.

API (REST JSON, préfixe /api/v1, session cookie, CSRF actif)

Rôles : anon (non connecté), owner (propriétaire du projet), user (connecté). Tout accès à un projet d'autrui renvoie 404 (RM-11, CA-22). Erreurs communes : 401 (session expirée), 404, 429 (limite de débit, H).

Intégrations externes

Sécurité et données personnelles

1. Authentification : mots de passe hachés (argon2id, H), cookie HttpOnly/Secure/SameSite=Lax, lien magique à usage unique expirant sous 15 min H, limitation de débit sur la connexion.
2. Autorisation : chaque requête filtre par owner_id (RM-11) ; refus renvoyé en 404 pour ne pas révéler l'existence du projet.
3. Clés BYOK : AES-256-GCM, clé maître en KMS UE ; la clé en clair n'apparaît ni dans les réponses (seul key_last4) ni dans les journaux (masquage systématique, test CA-18) ; l'appel au fournisseur se fait côté serveur uniquement (RM-09).
4. Entrées et sorties : validation de schéma sur chaque endpoint ; contenu IA rendu en Markdown assaini (pas de HTML brut) ; noms de fichiers du ZIP normalisés, sans .. ni chemin absolu (RM-10) ; secrets Stripe vérifiés par signature de webhook.
5. Protection contre les abus : Idempotency-Key obligatoire pour lancer ou reprendre ; index unique des générations actives (RM-05) ; plafond de messages de chat et de débit par utilisateur H.
6. RGPD : données stockées dans l'UE ; avertissement avant la 1ʳᵉ génération sur la sortie possible des données vers les fournisseurs IA (RM-13) ; suppression du compte et purge de projets, clés et historiques sous 30 jours (RM-14) ; journaux sans idée de projet ni contenu de dossier H.

Limite : les valeurs marquées H sont à confirmer ; aucune mesure de charge n'a été réalisée.

Conventions : TS strict, Next.js, PostgreSQL. Chaque tâche livre du code + tests. Ordre = dépendances. Les corrections « corrige EC-xx » sont intégrées dans les tâches (dont ajout de RM-15 : plan free = 3 Rapides au total, free_quota_used +1 par génération, en transaction avec verrou sur subscriptions, restitué si annulée sans section ou échec ; BYOK = quota_units = 0).

Jalon J1 — Socle, comptes, projets, questionnaire (MVP-01, 07 partiel)

Jalon J2 — Clés BYOK, modèles, estimation (MVP-05, 02 partiel)

Jalon J3 — Facturation, quotas, autorisation de lancement (MVP-07, 02)

Jalon J4 — Génération asynchrone et dossier (MVP-02, 03)

Jalon J5 — Chat, export, RGPD (MVP-04, 06, 07)

Couverture des critères d'acceptation

Écarts corrigés : EC-01 (T-16, T-17), EC-02 (T-16), EC-03 (T-16), EC-04 (T-15), EC-05 (T-03, T-26), EC-06 (T-02, T-11), EC-07 (T-07), EC-08 (T-02, T-11), EC-09 (T-25).

Écarts

Hypothèses à vérifier en premier

1. Estimation fiable du coût/durée avant lancement (D-02) — risque : fourchette fausse, lancement bloqué (RM-04) ou coût sous-estimé ; vérifier sur quelques idées types le ratio estimé/réel.
2. Marge économique de Solo à 15 €/mois (30 Rapides ou 10 Complètes, modèles plateforme) — risque : coût IA supérieur au prix ; chiffrer le coût moyen d'une Complète avec vérification web avant de fixer les quotas.
3. TVA/Stripe Tax et prix « TTC » pour particuliers (D-06) et sortie de données hors UE vers les fournisseurs IA (D-04/RM-13) — risque juridique RGPD/TVA ; faire valider par un juriste (DPA des fournisseurs, base légale, mention TTC vs HT).

• Claude Code now supports AGENTS.md Natively - Here's how it actually works - DEV Community
• AGENTS.md Spec (2026): Recommended Sections + AGENTS.md vs CLAUDE.md vs .cursorrules
• CLAUDE.md, AGENTS.md & Copilot Instructions: Configure Every AI Coding Assistant
• AGENTS.md Guide 2026: Tool Support, Claude Code, Caveats
• How to Write AGENTS.md: Templates, Best Practices, and Multi-Tool Support (2026) — The Prompt Shelf
• What Is AGENTS.md? A Guide for AI Coding Agents
• AGENTS.md vs CLAUDE.md: Does Claude Code or Codex Read Both?
• What is AGENTS.md, and why Claude Code now reads it
• AGENTS.md: Format, Example, vs CLAUDE.md, and Generator
• AGENTS.md Guide (2026): Copilot, Cursor & More
• Stripe VAT in Germany: Registration & Filing
• VAT (Value-Added Tax) and SaaS (Software as a Service)
• Tax for digital products
• How the VAT OSS scheme works for Dutch companies
• VAT registration in Europe in 2027: A practical guide
• What is EU value-added tax (VAT) & VAT OSS?
• EU VAT for a SaaS with Stripe Tax: OSS, reverse charge and VIES - DEV Community
• 16 Tax Compliance Tools for SaaS Using Stripe: What Stripe Tax Actually Covers (And What It Doesn't)
• Navigating the VAT registration process in Europe
• Introduction to EU VAT and European VAT OSS