From e14f045b42ef52670f198c70978aebc16a6eaeab Mon Sep 17 00:00:00 2001 From: David Blanc Brioir Date: Sun, 14 Dec 2025 00:59:50 +0100 Subject: [PATCH] Add guide and template for creating new applications --- GUIDE_NEW_APP.md | 332 ++++++++++++++++++++++++++++++++++ README.md | 20 +- prompts/app_spec_template.txt | 132 ++++++++++++++ 3 files changed, 483 insertions(+), 1 deletion(-) create mode 100644 GUIDE_NEW_APP.md create mode 100644 prompts/app_spec_template.txt diff --git a/GUIDE_NEW_APP.md b/GUIDE_NEW_APP.md new file mode 100644 index 0000000..a0388e1 --- /dev/null +++ b/GUIDE_NEW_APP.md @@ -0,0 +1,332 @@ +# Guide : Créer une Nouvelle Application avec le Framework Linear Coding + +Ce guide explique comment utiliser ce framework pour créer une **toute nouvelle application** à partir de zéro. + +## Vue d'ensemble + +Ce framework permet de générer automatiquement une application complète en utilisant : +- **Linear** pour la gestion de projet (issues, suivi, commentaires) +- **Claude Agent SDK** pour le développement autonome +- **Spécifications en format XML** pour décrire l'application + +## Structure du Framework + +### Fichiers génériques (à NE PAS modifier) + +Ces fichiers font partie du framework et sont réutilisables pour toutes les applications : + +``` +linear-coding-agent/ +├── autonomous_agent_demo.py # Point d'entrée principal +├── agent.py # Logique des sessions d'agent +├── client.py # Configuration SDK Claude + MCP +├── security.py # Validation et whitelist des commandes +├── progress.py # Utilitaires de suivi de progression +├── prompts.py # Utilitaires de chargement des prompts +├── linear_config.py # Constantes de configuration Linear +├── requirements.txt # Dépendances Python +└── prompts/ + ├── initializer_prompt.md # Prompt pour la session initiale + ├── initializer_bis_prompt.md # Prompt pour ajouter des features + └── coding_prompt.md # Prompt pour les sessions de codage +``` + +**⚠️ Ne modifiez PAS ces fichiers** - ils sont génériques et fonctionnent pour toutes les applications. + +### Fichiers spécifiques à votre application (à CRÉER) + +Le seul fichier que vous devez créer est : + +``` +prompts/ +└── app_spec.txt # Votre spécification d'application (format XML) +``` + +## Étapes pour Créer une Nouvelle Application + +### Étape 1 : Créer votre fichier de spécification + +Créez un fichier `prompts/app_spec.txt` qui décrit votre application. Utilisez le format XML suivant : + +```xml + + Nom de Votre Application + + + Description complète de votre application. Expliquez ce que vous voulez construire, + les objectifs principaux, et les fonctionnalités clés. + + + + + React avec Vite + Tailwind CSS + React hooks + + + + Node.js avec Express + SQLite + + + + + + + - Liste des prérequis (dépendances, clés API, etc.) + + + + + + Titre de la fonctionnalité 1 + Description détaillée + 1 + frontend + + 1. Étape de test 1 + 2. Étape de test 2 + + + + + + + + +``` + +### Étape 2 : Exemple de structure complète + +Voici un exemple basé sur l'application "Claude Clone" que vous pouvez utiliser comme référence : + +**Structure recommandée de `app_spec.txt` :** + +```xml + + Mon Application + + + Description de votre application... + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +### Étape 3 : Lancer l'initialisation + +Une fois votre `app_spec.txt` créé, lancez l'agent initializer : + +```bash +python autonomous_agent_demo.py --project-dir ./ma_nouvelle_app +``` + +L'agent va : +1. Lire votre `app_spec.txt` +2. Créer un projet Linear +3. Créer ~50 issues Linear basées sur votre spécification +4. Initialiser la structure du projet + +### Étape 4 : Suivre le développement + +Les agents de codage vont ensuite : +- Travailler sur les issues Linear une par une +- Implémenter les fonctionnalités +- Tester avec Puppeteer +- Mettre à jour les issues avec leurs commentaires + +## Exemple : Utiliser l'application "Claude Clone" comme référence + +L'application "Claude Clone" dans `prompts/app_spec.txt` est un excellent exemple à suivre car elle contient : + +### ✅ Éléments à copier/adapter : + +1. **Structure XML** : La structure générale avec ``, ``, ``, etc. + +2. **Format des fonctionnalités** : Comment structurer les `` avec : + - `` + - `<description>` + - `<priority>` + - `<category>` + - `<test_steps>` + +3. **Détails techniques** : Comment décrire : + - La stack technologique + - Les prérequis + - Les endpoints API + - Le schéma de base de données + - Les spécifications UI + +### ❌ Éléments spécifiques à NE PAS copier : + +1. **Le contenu spécifique** : Les détails sur "Claude API", "artifacts", "conversations", etc. sont spécifiques à cette app +2. **Les fonctionnalités métier** : Adaptez-les à votre application + +## Checklist pour une Nouvelle Application + +- [ ] Créer `prompts/app_spec.txt` avec votre spécification +- [ ] Définir le `<project_name>` de votre application +- [ ] Décrire l'`<overview>` complète +- [ ] Spécifier la `<technology_stack>` (frontend + backend) +- [ ] Lister les `<prerequisites>` nécessaires +- [ ] Définir toutes les `<core_features>` avec des balises `<feature_X>` +- [ ] Ajouter des `<test_steps>` pour chaque fonctionnalité +- [ ] Lancer : `python autonomous_agent_demo.py --project-dir ./mon_app` +- [ ] Vérifier dans Linear que les issues sont créées correctement + +## Conseils pour Rédiger une Bonne Spécification + +### 1. Soyez détaillé mais structuré + +Chaque fonctionnalité doit avoir : +- Un titre clair +- Une description complète de ce qu'elle fait +- Des étapes de test précises +- Une priorité (1=urgent, 4=optionnel) + +### 2. Utilisez le format XML cohérent + +```xml +<feature_1> + <title>Authentification - Connexion utilisateur + + Implémenter un système d'authentification avec : + - Formulaire de connexion (email/mot de passe) + - Validation côté client et serveur + - Gestion des sessions avec JWT + - Page de réinitialisation de mot de passe + + 1 + auth + + 1. Accéder à la page de connexion + 2. Entrer un email invalide → voir erreur + 3. Entrer des identifiants valides → redirection vers dashboard + 4. Vérifier que le token JWT est stocké + 5. Tester la déconnexion + + +``` + +### 3. Organisez par catégories + +Groupez les fonctionnalités par catégorie : +- `auth` : Authentification +- `frontend` : Interface utilisateur +- `backend` : API et logique serveur +- `database` : Modèles et migrations +- `integration` : Intégrations externes + +### 4. Priorisez les fonctionnalités + +- **Priority 1** : Fonctionnalités critiques (auth, base de données) +- **Priority 2** : Fonctionnalités importantes (core features) +- **Priority 3** : Fonctionnalités secondaires (améliorations UX) +- **Priority 4** : Nice-to-have (polish, optimisations) + +## Exemple Minimal + +Voici un exemple minimal pour démarrer : + +```xml + + Todo App - Gestionnaire de Tâches + + + Application web simple pour gérer des listes de tâches. + Les utilisateurs peuvent créer, modifier, compléter et supprimer des tâches. + + + + + React avec Vite + Tailwind CSS + + + Node.js avec Express + SQLite + + + + + + Interface principale - Liste des tâches + Afficher une liste de toutes les tâches avec leur statut + 1 + frontend + + 1. Ouvrir l'application + 2. Vérifier que la liste des tâches s'affiche + + + + + Créer une nouvelle tâche + Formulaire pour ajouter une nouvelle tâche à la liste + 1 + frontend + + 1. Cliquer sur "Nouvelle tâche" + 2. Entrer un titre + 3. Cliquer sur "Ajouter" + 4. Vérifier que la tâche apparaît dans la liste + + + + +``` + +## Fichiers à Conserver du Framework + +Ces fichiers sont **génériques** et fonctionnent pour toutes les applications : + +- ✅ `autonomous_agent_demo.py` - Point d'entrée +- ✅ `agent.py` - Logique des agents +- ✅ `client.py` - Configuration Claude SDK +- ✅ `prompts.py` - Chargement des prompts +- ✅ `progress.py` - Suivi de progression +- ✅ `security.py` - Sécurité +- ✅ `linear_config.py` - Config Linear +- ✅ `prompts/initializer_prompt.md` - Template initializer +- ✅ `prompts/initializer_bis_prompt.md` - Template initializer bis +- ✅ `prompts/coding_prompt.md` - Template coding agent +- ✅ `requirements.txt` - Dépendances Python + +## Fichiers à Créer pour Votre Application + +- ✅ `prompts/app_spec.txt` - **Votre spécification (le seul fichier à créer !)** + +## Résumé + +Pour créer une nouvelle application : + +1. **Copiez la structure XML** de `prompts/app_spec.txt` (exemple Claude Clone) +2. **Adaptez le contenu** à votre application +3. **Définissez toutes vos fonctionnalités** avec des balises `` +4. **Lancez** : `python autonomous_agent_demo.py --project-dir ./mon_app` +5. **Suivez le progrès** dans Linear + +Le framework s'occupe du reste ! 🚀 diff --git a/README.md b/README.md index 21b7326..4e92c64 100644 --- a/README.md +++ b/README.md @@ -170,12 +170,14 @@ linear-agent-harness/ ├── prompts.py # Prompt loading utilities ├── linear_config.py # Linear configuration constants ├── prompts/ -│ ├── app_spec.txt # Application specification +│ ├── app_spec.txt # Application specification (Claude Clone example) +│ ├── app_spec_template.txt # Template for creating new applications │ ├── app_spec_theme_customization.txt # Example: Theme customization spec │ ├── app_spec_mistral_extensible.txt # Example: Mistral provider spec │ ├── initializer_prompt.md # First session prompt (creates Linear issues) │ ├── initializer_bis_prompt.md # Prompt for adding new features │ └── coding_prompt.md # Continuation session prompt (works issues) +├── GUIDE_NEW_APP.md # Guide pour créer une nouvelle application └── requirements.txt # Python dependencies ``` @@ -226,6 +228,22 @@ All subsequent coding agents will work from this Linear project. ## Customization +### Creating a New Application from Scratch + +To create a **completely new application** (not based on the Claude Clone example): + +1. **Read the guide**: See [GUIDE_NEW_APP.md](GUIDE_NEW_APP.md) for detailed instructions +2. **Use the template**: Copy `prompts/app_spec_template.txt` as a starting point +3. **Reference the example**: Use `prompts/app_spec.txt` (Claude Clone) as a reference for structure and detail level +4. **Create your spec**: Write your `prompts/app_spec.txt` with your application specification +5. **Launch**: Run `python autonomous_agent_demo.py --project-dir ./my_new_app` + +**Key points:** +- Keep the framework files unchanged (they're generic and reusable) +- Only create/modify `prompts/app_spec.txt` for your new application +- Use the XML structure from the Claude Clone example as a template +- Define features with `` tags - each will become a Linear issue + ### Changing the Application Edit `prompts/app_spec.txt` to specify a different application to build. diff --git a/prompts/app_spec_template.txt b/prompts/app_spec_template.txt new file mode 100644 index 0000000..7a1fa84 --- /dev/null +++ b/prompts/app_spec_template.txt @@ -0,0 +1,132 @@ + + Votre Nom d'Application + + + Description complète de votre application. Expliquez : + - Ce que fait l'application + - Qui sont les utilisateurs cibles + - Les objectifs principaux + - Les fonctionnalités clés en quelques phrases + + + + + Note: Vous pouvez utiliser une clé API située à /tmp/api-key pour les tests. + Vous ne pourrez pas lire ce fichier, mais vous pouvez le référencer dans le code. + + + React avec Vite + Tailwind CSS (via CDN) + React hooks et context + React Router pour la navigation + Lancer uniquement sur le port {frontend_port} + + + Node.js avec Express + SQLite avec better-sqlite3 + Intégration avec les APIs nécessaires + Server-Sent Events pour les réponses en temps réel (si nécessaire) + + + Endpoints RESTful + SSE pour le streaming en temps réel (si nécessaire) + + + + + + - Repository inclut .env avec les clés API configurées + - Dépendances frontend pré-installées via npm/pnpm + - Code backend dans le répertoire /server + - Installer les dépendances backend au besoin + + + + + + + + Nom de la fonctionnalité 1 + + Description détaillée de ce que fait cette fonctionnalité. + Incluez les détails techniques importants, les cas d'usage, et les + interactions avec d'autres parties de l'application. + + 1 + frontend + + 1. Étape de test 1 - décrire l'action + 2. Étape de test 2 - décrire l'action + 3. Étape de test 3 - vérifier le résultat attendu + 4. Étape de test 4 - tester les cas d'erreur + + + + + Nom de la fonctionnalité 2 + + Description de la fonctionnalité 2... + + 2 + backend + + 1. Étape de test 1 + 2. Étape de test 2 + + + + + + + + + + + + + + + + + + + + + +