🧭 Cursor – Guide complet pour le développement agentique

Avant Cursor / avec Cursor

Cursor vs autres approches

Cas d’usage très rentables

Ce que Cursor ne doit pas décider seul

Préparer un projet existant

Repository preparation:
- README.md
- AGENTS.md
- .cursor/rules/
- scripts/check.sh
- scripts/test.sh
- docs/architecture.md
- docs/runbook.md
- .env.example
- tests/

Structure minimale recommandée

project-root/
  app/
  config/
  tests/
  docs/
    architecture.md
    runbook.md
  scripts/
    test.sh
    lint.sh
    check_migrations.sh
  .cursor/
    rules/
      project.mdc
      django.mdc
      security.mdc
  AGENTS.md

Indexation et contexte

Cursor fonctionne mieux quand le codebase est indexé proprement. L’indexation permet au chat et à l’agent de retrouver des symboles, chemins, usages et fichiers pertinents.

Choix des modèles

Cursor permet de choisir des modèles différents selon les tâches. La logique saine n’est pas “toujours le plus puissant”, mais “le modèle adapté au risque”.

Confidentialité et politiques d’équipe

Avant un usage professionnel, il faut clarifier : code privé, secrets, données clients, logs, prompts, modèles autorisés, stockage de contexte, outils externes et accès MCP.

Security baseline:
- never paste secrets
- never expose customer data in prompts
- use .env.example instead of .env
- mask tokens in logs
- require review for auth and permissions
- require tests for data migrations
- require explicit approval for destructive commands

Chat : questionner le dépôt

Le Chat sert à comprendre, diagnostiquer, comparer, demander une stratégie. Il est idéal avant l’Agent, car il permet d’éviter de modifier trop vite.

Good chat prompts:
1. Explain how this module works. Do not edit files.
2. Find the likely source of this error. Give hypotheses only.
3. Map all files involved in this workflow.
4. Propose a minimal patch plan. No code yet.
5. Review this diff for bugs, security risks, and migration risks.

Inline Edit : chirurgie locale

Inline Edit est utile pour transformer une sélection précise : simplifier, renommer, sécuriser, ajouter logs, rendre une fonction plus robuste.

Choisir le bon geste

Workflow agentique sérieux

Contrôler les outils

Le vrai danger n’est pas que l’agent écrive du code ; le vrai danger est qu’il lance des commandes ou modifie des fichiers au mauvais périmètre.

Safe commands:
python manage.py test app.tests.test_feature
python manage.py check
python manage.py makemigrations --check --dry-run
python -m pytest tests/test_feature.py
ruff check app/

Commands requiring approval:
pip install package
python manage.py migrate
python manage.py flush
git push

Gestion des erreurs

Checklist avant d’accepter un diff agentique

• Le diff est-il limité à la demande ?
• Chaque fichier changé est-il justifié ?
• Les tests pertinents ont-ils été lancés ?
• Les erreurs existantes sont-elles distinguées des nouvelles ?
• Pas de changement de dépendance non demandé ?
• Pas de secret, token, chemin local, donnée client ?
• Pas de migration dangereuse ou index long ?
• Le rollback est-il simple ?

Plan d’implémentation idéal

Questions que Cursor doit poser

• Quelle version de compatibilité doit être conservée ?
• Peut-on modifier le schéma de base de données ?
• Quels tests sont fiables dans ce projet ?
• La fonctionnalité doit-elle rester compatible avec une API existante ?
• Faut-il préserver une convention interne non documentée ?
• Y a-t-il des contraintes de performance ou de sécurité ?

Valider ou refuser un plan

Approval prompt:
The plan is mostly correct.
Implement only step 1.
Do not modify public APIs.
Do not add dependencies.
After editing, show the diff summary and run the targeted test command.

Exemple de règles projet

Project rules:
- Produce small, reviewable patches.
- Never rewrite a full file unless explicitly requested.
- Before editing, identify the files you need to change.
- Do not add dependencies without approval.
- Do not run destructive commands.
- Prefer explicit error handling over silent failures.
- Keep public APIs backward compatible unless approved.
- Add or update tests for behavior changes.
- Explain database migration risks before creating migrations.

AGENTS.md minimal

# Agent instructions

## Commands
- Run tests: python manage.py test
- Check project: python manage.py check
- Check migrations: python manage.py makemigrations --check --dry-run

## Architecture
- Business logic belongs in services.
- Views should stay thin.
- Management commands must support --verbosity.

## Safety
- Never modify .env files.
- Never run production commands.
- Ask before adding dependencies.
- Ask before creating migrations.

Rules spécialisées Django/Python

Django rules:
- Do not create indexes on very long text-like fields.
- Use application-level deduplication when requested.
- Avoid large model rewrites.
- For migrations, explain database impact first.
- Management commands must be observable and testable.
- Prefer select_related and prefetch_related for ORM performance.
- Never hide exceptions with a broad except block.
- Keep template JavaScript isolated and deterministic.
- Do not put secrets in settings or templates.
- Use English identifiers and comments in code.

Anti-règles : trop vague, trop long, contradictoire

Donner le bon contexte

Éviter la noyade contextuelle

Plus de contexte n’est pas toujours mieux. Trop de fichiers, de logs ou d’anciennes versions peut polluer la réponse.

Bad prompt:
Fix everything in this app.

Good prompt:
Analyze this failing test only.
Do not edit files.
Explain why it fails and propose one minimal patch.

Méthode MCE appliquée à Cursor

Skills : packager une compétence

Les Skills servent à donner à l’agent des capacités réutilisables : scripts, connaissances, conventions, procédures. C’est utile pour industrialiser les tâches fréquentes.

Skill examples:
- Django migration risk reviewer
- SQL performance checklist
- Release notes generator
- Security review checklist
- Legacy module mapper
- Test scaffold generator
- Incident runbook writer

Subagents : spécialiser les rôles

Un subagent peut être spécialisé pour une tâche : reviewer sécurité, expert tests, cartographe de code, spécialiste migrations, analyste performance.

Hooks : automatiser autour de l’agent

Les hooks permettent de déclencher des contrôles ou comportements autour des actions agentiques. Ils doivent rester simples, observables et non destructifs.

Risques MCP / Skills / Hooks

• Permissions trop larges.
• Données sensibles exposées.
• Outils non déterministes.
• Commandes destructives.
• Prompt injection via documentation ou tickets.
• Coûts imprévus si agents répètent des scans.

Cloud Agents

Les agents cloud permettent de lancer des tâches dans un environnement distant. C’est intéressant pour du travail parallèle, mais cela exige une isolation stricte et une revue de branche.

Branches et worktrees

La bonne pratique est de faire travailler les agents dans des branches isolées. Un agent = une tâche = une branche = une PR reviewable.

Branch discipline:
feature/cursor-fix-user-export
feature/cursor-tests-billing-service
refactor/cursor-split-search-parser
docs/cursor-runbook-srdf-daemon

Never mix:
- unrelated refactor
- dependency upgrade
- bug fix
- formatting sweep
in the same agent branch.

Cursor SDK

Cursor a introduit un SDK pour construire des agents programmatiques avec le même runtime que les agents de l’app, du CLI et du web. C’est une piste intéressante pour automatiser des tâches internes.

SDK use cases:
- repository summarizer
- migration risk bot
- release note generator
- stale code detector
- runbook assistant
- PR preparation helper
- internal quality agent

Workflow PR recommandé

Règles Bugbot utiles

Bugbot review rules:
- Flag missing authorization checks.
- Flag broad exception swallowing.
- Flag database migrations without rollback notes.
- Flag N+1 query risks in Django views and serializers.
- Flag secrets, tokens, or credentials.
- Flag changes that bypass existing service layer.
- Flag test changes that reduce coverage.
- Flag long indexes on text-like fields.

Limites de la revue IA

• Peut ne pas comprendre un invariant métier non documenté.
• Peut sur-signaler des risques théoriques.
• Peut manquer un bug qui dépend de données réelles.
• Peut être trompé par un diff trop gros.
• Ne remplace pas tests, staging, observabilité.

Migrations : zone rouge

Migration prompt:
Analyze the model change only.
Do not create a migration yet.
Explain:
1. database operations needed
2. lock risk
3. data migration risk
4. index risk
5. rollback strategy
6. tests and checks to run

Management commands : ton terrain naturel

Cursor peut aider à produire des crons sérieux, mais il faut imposer observabilité, options, dry-run, counters, exports et logs.

Management command requirements:
- --dry-run
- --limit
- --verbosity
- --debug
- --export-json
- --export-excel if needed
- progress counters
- final summary
- explicit error report
- idempotent behavior when possible

Templates IDEO-Lab

Cursor peut manipuler tes guides HTML, mais il faut lui interdire de casser l’architecture modals/cartes/tabs.

Template rules:
- Keep the existing kgrid/kcard/ig-modal architecture.
- Do not change global base template blocks.
- Keep modal ids unique.
- Keep data-open and data-close attributes consistent.
- Keep JavaScript generic.
- Do not duplicate modal handlers.
- Keep CSS scoped with the page prefix.

Tests Django à demander à Cursor

Patch ciblé

Implement the smallest possible patch for the approved plan.

Constraints:
- change only the required files
- do not add dependencies
- do not change public APIs
- do not create migrations
- keep existing style
- after editing, summarize every changed file
- run the targeted test command

Review sévère

Review this diff as a strict senior engineer.

Check:
- correctness
- security
- database impact
- performance
- backward compatibility
- error handling
- tests
- maintainability

Return blocking issues first.
Do not rewrite code unless asked.

Génération de tests

Create tests for this behavior.

Rules:
- cover nominal case
- cover edge cases
- cover regression case
- do not mock the function under test
- keep fixtures small
- name tests clearly
- explain how to run only these tests

Refactor contrôlé

Refactor this code without changing behavior.

Constraints:
- preserve public API
- preserve database schema
- preserve output format
- no dependency changes
- split into steps if needed
- add tests only if behavior is currently untested
- show risk analysis before editing

Auto-run et commandes

L’auto-run peut accélérer, mais il doit être limité. Les commandes de lecture et de test sont acceptables ; les commandes destructives doivent être bloquées.

Security Review

Cursor propose des agents de revue sécurité pour les plans Teams et Enterprise : revue de PR et scan de vulnérabilités. C’est une couche utile, mais elle doit compléter les outils existants.

Contrôle des coûts

Les équipes doivent suivre la consommation par surface : clients, agents cloud, automatisations, Bugbot, Security Review. Les modèles puissants et les agents longs coûtent plus cher.

Politique d’entreprise

Enterprise Cursor policy:
1. Define allowed repositories
2. Define allowed models and providers
3. Define data handling rules
4. Define MCP allowlist
5. Require PR review for agent changes
6. Require CI before merge
7. Monitor usage by surface
8. Train developers on prompt and diff review
9. Keep security rules updated
10. Audit incidents and improve rules

Standards obligatoires

• Une tâche agentique = une branche.
• Un patch agentique = un diff reviewable.
• Tout changement métier = test.
• Tout changement DB = plan migration.
• Tout changement auth = review sécurité.
• Tout agent cloud = PR et CI.
• Tout faux positif Bugbot utile = règle améliorée.

Métriques utiles

Former les développeurs

La formation Cursor ne doit pas être une démo magique. Elle doit apprendre les réflexes : contexte, plan, patch, test, review, rollback.

Training path:
Day 1: Tab, Chat, Inline Edit
Day 2: Agent with small bug fixes
Day 3: Rules and context engineering
Day 4: Tests and review workflow
Day 5: Security, MCP, Cloud Agents
Day 6: Team standards and CI integration

Bugfix

Feature

Refactor

Refactor protocol:
1. map current behavior
2. add characterization tests if missing
3. refactor one unit
4. run tests
5. compare diff
6. repeat

Fonctionnalités 2026 à surveiller

Checklist de veille mensuelle

Monthly Cursor watch:
- read latest changelog
- check model policy changes
- review team usage analytics
- update project rules
- update security rules
- verify MCP permissions
- review agent failures and false positives
- improve prompts and runbooks
- train team on new features