dify/AGENTS.md

AGENTS.md

Project Overview

Dify is an open-source platform for developing LLM applications with an intuitive interface combining agentic AI workflows, RAG pipelines, agent capabilities, and model management.

The codebase is split into:

• Backend API (/api): Python Flask application organized with Domain-Driven Design
• Frontend Web (/web): Next.js application using TypeScript and React
• Docker deployment (/docker): Containerized deployment configurations

Backend Workflow

• Read api/AGENTS.md for details
• Run backend CLI commands through uv run --project api <command>.
• Integration tests are CI-only and are not expected to run in the local environment.

Frontend Workflow

• Read web/AGENTS.md for details

Testing & Quality Practices

• Follow TDD: red → green → refactor.
• Use pytest for backend tests with Arrange-Act-Assert structure.
• Enforce strong typing; avoid Any and prefer explicit type annotations.
• Write self-documenting code; only add comments that explain intent.

Language Style

• Python: Keep type hints on functions and attributes, and implement relevant special methods (e.g., __repr__, __str__). Prefer TypedDict over dict or Mapping for type safety and better code documentation.
• TypeScript: Use the strict config, rely on ESLint (pnpm lint:fix preferred) plus pnpm type-check:tsgo, and avoid any types.

General Practices

• Prefer editing existing files; add new documentation only when requested.
• Inject dependencies through constructors and preserve clean architecture boundaries.
• Handle errors with domain-specific exceptions at the correct layer.

Cherry-Picking to LTS Branches

• Always use git cherry-pick -x when backporting commits from main to any lts/* branch.
• The -x flag appends (cherry picked from commit <sha>) to the commit message. CI validates this provenance line; commits without it will fail.
• When cherry-picking multiple commits, each must carry its own (cherry picked from ...) annotation.
• Run git cherry-pick --continue with HUSKY=0 to skip pre-existing lint errors that are unrelated to the fix.

Project Conventions

• Backend architecture adheres to DDD and Clean Architecture principles.
• Async work runs through Celery with Redis as the broker.
• Frontend user-facing strings must use web/i18n/en-US/; avoid hardcoded text.