Add guide and template for creating new applications

This commit is contained in:
2025-12-14 00:59:50 +01:00
parent a310d4b3cf
commit e14f045b42
3 changed files with 483 additions and 1 deletions

332
GUIDE_NEW_APP.md Normal file
View File

@@ -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
<project_specification>
<project_name>Nom de Votre Application</project_name>
<overview>
Description complète de votre application. Expliquez ce que vous voulez construire,
les objectifs principaux, et les fonctionnalités clés.
</overview>
<technology_stack>
<frontend>
<framework>React avec Vite</framework>
<styling>Tailwind CSS</styling>
<state_management>React hooks</state_management>
<!-- Ajoutez d'autres technologies frontend -->
</frontend>
<backend>
<runtime>Node.js avec Express</runtime>
<database>SQLite</database>
<!-- Ajoutez d'autres technologies backend -->
</backend>
</technology_stack>
<prerequisites>
<environment_setup>
- Liste des prérequis (dépendances, clés API, etc.)
</environment_setup>
</prerequisites>
<core_features>
<feature_1>
<title>Titre de la fonctionnalité 1</title>
<description>Description détaillée</description>
<priority>1</priority>
<category>frontend</category>
<test_steps>
1. Étape de test 1
2. Étape de test 2
</test_steps>
</feature_1>
<feature_2>
<!-- Autres fonctionnalités -->
</feature_2>
</core_features>
</project_specification>
```
### É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
<project_specification>
<project_name>Mon Application</project_name>
<overview>
Description de votre application...
</overview>
<technology_stack>
<!-- Stack technique complète -->
</technology_stack>
<prerequisites>
<!-- Prérequis -->
</prerequisites>
<core_features>
<!-- Liste toutes vos fonctionnalités avec des balises <feature_X> -->
</core_features>
<ui_design>
<!-- Spécifications UI si nécessaire -->
</ui_design>
<api_endpoints>
<!-- Endpoints API si nécessaire -->
</api_endpoints>
<database_schema>
<!-- Schéma de base de données si nécessaire -->
</database_schema>
</project_specification>
```
### É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 `<project_specification>`, `<overview>`, `<technology_stack>`, etc.
2. **Format des fonctionnalités** : Comment structurer les `<feature_X>` avec :
- `<title>`
- `<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</title>
<description>
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
</description>
<priority>1</priority>
<category>auth</category>
<test_steps>
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
</test_steps>
</feature_1>
```
### 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
<project_specification>
<project_name>Todo App - Gestionnaire de Tâches</project_name>
<overview>
Application web simple pour gérer des listes de tâches.
Les utilisateurs peuvent créer, modifier, compléter et supprimer des tâches.
</overview>
<technology_stack>
<frontend>
<framework>React avec Vite</framework>
<styling>Tailwind CSS</styling>
</frontend>
<backend>
<runtime>Node.js avec Express</runtime>
<database>SQLite</database>
</backend>
</technology_stack>
<core_features>
<feature_1>
<title>Interface principale - Liste des tâches</title>
<description>Afficher une liste de toutes les tâches avec leur statut</description>
<priority>1</priority>
<category>frontend</category>
<test_steps>
1. Ouvrir l'application
2. Vérifier que la liste des tâches s'affiche
</test_steps>
</feature_1>
<feature_2>
<title>Créer une nouvelle tâche</title>
<description>Formulaire pour ajouter une nouvelle tâche à la liste</description>
<priority>1</priority>
<category>frontend</category>
<test_steps>
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
</test_steps>
</feature_2>
</core_features>
</project_specification>
```
## 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 `<feature_X>`
4. **Lancez** : `python autonomous_agent_demo.py --project-dir ./mon_app`
5. **Suivez le progrès** dans Linear
Le framework s'occupe du reste ! 🚀

View File

@@ -170,12 +170,14 @@ linear-agent-harness/
├── prompts.py # Prompt loading utilities ├── prompts.py # Prompt loading utilities
├── linear_config.py # Linear configuration constants ├── linear_config.py # Linear configuration constants
├── prompts/ ├── 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_theme_customization.txt # Example: Theme customization spec
│ ├── app_spec_mistral_extensible.txt # Example: Mistral provider spec │ ├── app_spec_mistral_extensible.txt # Example: Mistral provider spec
│ ├── initializer_prompt.md # First session prompt (creates Linear issues) │ ├── initializer_prompt.md # First session prompt (creates Linear issues)
│ ├── initializer_bis_prompt.md # Prompt for adding new features │ ├── initializer_bis_prompt.md # Prompt for adding new features
│ └── coding_prompt.md # Continuation session prompt (works issues) │ └── coding_prompt.md # Continuation session prompt (works issues)
├── GUIDE_NEW_APP.md # Guide pour créer une nouvelle application
└── requirements.txt # Python dependencies └── requirements.txt # Python dependencies
``` ```
@@ -226,6 +228,22 @@ All subsequent coding agents will work from this Linear project.
## Customization ## 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 `<feature_X>` tags - each will become a Linear issue
### Changing the Application ### Changing the Application
Edit `prompts/app_spec.txt` to specify a different application to build. Edit `prompts/app_spec.txt` to specify a different application to build.

View File

@@ -0,0 +1,132 @@
<project_specification>
<project_name>Votre Nom d'Application</project_name>
<overview>
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
</overview>
<technology_stack>
<api_key>
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.
</api_key>
<frontend>
<framework>React avec Vite</framework>
<styling>Tailwind CSS (via CDN)</styling>
<state_management>React hooks et context</state_management>
<routing>React Router pour la navigation</routing>
<port>Lancer uniquement sur le port {frontend_port}</port>
</frontend>
<backend>
<runtime>Node.js avec Express</runtime>
<database>SQLite avec better-sqlite3</database>
<api_integration>Intégration avec les APIs nécessaires</api_integration>
<streaming>Server-Sent Events pour les réponses en temps réel (si nécessaire)</streaming>
</backend>
<communication>
<api>Endpoints RESTful</api>
<streaming>SSE pour le streaming en temps réel (si nécessaire)</streaming>
</communication>
</technology_stack>
<prerequisites>
<environment_setup>
- 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
</environment_setup>
</prerequisites>
<core_features>
<!--
IMPORTANT: Créez une balise <feature_X> pour chaque fonctionnalité.
L'agent initializer créera une issue Linear pour chaque feature.
Utilisez des numéros séquentiels: feature_1, feature_2, feature_3, etc.
-->
<feature_1>
<title>Nom de la fonctionnalité 1</title>
<description>
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.
</description>
<priority>1</priority>
<category>frontend</category>
<test_steps>
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
</test_steps>
</feature_1>
<feature_2>
<title>Nom de la fonctionnalité 2</title>
<description>
Description de la fonctionnalité 2...
</description>
<priority>2</priority>
<category>backend</category>
<test_steps>
1. Étape de test 1
2. Étape de test 2
</test_steps>
</feature_2>
<!--
Continuez à ajouter des features...
L'agent créera environ 50 issues au total, donc détaillez bien vos fonctionnalités
en les divisant en sous-fonctionnalités si nécessaire.
-->
</core_features>
<ui_design>
<!--
Optionnel: Décrivez le design UI si nécessaire
- Layout général
- Couleurs et thème
- Composants réutilisables
- Responsive design
-->
</ui_design>
<api_endpoints>
<!--
Optionnel: Liste des endpoints API si nécessaire
<endpoint>
<method>POST</method>
<path>/api/users</path>
<description>Créer un nouvel utilisateur</description>
<request_body>JSON avec email, password</request_body>
<response>JSON avec user_id, email</response>
</endpoint>
-->
</api_endpoints>
<database_schema>
<!--
Optionnel: Schéma de base de données si nécessaire
<table>
<name>users</name>
<columns>
<column>id INTEGER PRIMARY KEY</column>
<column>email TEXT UNIQUE</column>
<column>password_hash TEXT</column>
<column>created_at DATETIME</column>
</columns>
</table>
-->
</database_schema>
<deployment>
<!--
Optionnel: Instructions de déploiement si nécessaire
-->
</deployment>
</project_specification>