CodeReview/AGENTS.md

DeepAudit Agent Instructions

This guide provides essential technical information for agentic coding tools operating within the DeepAudit repository.

🛠 Development Commands

Backend (Python/FastAPI)

Located in /backend. Uses uv for environment management and pytest for testing.

• Sync Environment: uv sync
• Start Server: uvicorn app.main:app --reload
• Run All Tests: pytest
• Run Agent Tests: python tests/agent/run_tests.py
• Run Single Test: pytest tests/agent/test_agents.py::test_name
• Linting: ruff check .
• Formatting: black .
• Type Checking: mypy .
• Database Migrations: alembic upgrade head

Frontend (React/TypeScript)

Located in /frontend. Uses pnpm and Vite.

• Install Dependencies: pnpm install
• Start Dev Server: pnpm dev
• Build Project: pnpm build
• Linting: pnpm lint
• Format: pnpm format
• Type Checking: pnpm type-check

---

🎨 Code Style & Conventions

General

• Language: English for code (variables, functions, comments), though some documentation/logs may be in Chinese.
• Architecture: Follow the Multi-Agent architecture. Backend logic for agents is in backend/app/agents/.

Backend (Python)

• Style: PEP 8 via black (100 char limit) and ruff.
• Typing: Strict type hinting is required. Use Pydantic models for data validation in backend/app/schemas/.
• Imports:
  • Standard library first.
  • Third-party libraries second.
  • Local application imports last (using app.xxx absolute paths).
• Naming: snake_case for variables/functions, PascalCase for classes.
• Error Handling: Use custom exceptions where appropriate. FastAPI's HTTPException for API responses. Prefer logger.error over print.
• Database: SQLAlchemy 2.0 (async). Models in backend/app/models/.

Frontend (React/TypeScript)

• Framework: React 18+ with Vite and TypeScript.
• State Management: Zustand for stores.
• UI Components: Shadcn/UI (Radix UI) + Tailwind CSS.
• Structure:
  • src/features/: Domain-specific components and logic.
  • src/components/ui/: Shared low-level components.
  • src/shared/: Cross-cutting concerns (hooks, types, utils, api).
• Types: Define interfaces in src/shared/types/index.ts. Avoid any.
• Imports: Use absolute paths (e.g., @/components/... if configured, otherwise relative to src).
• Naming: PascalCase for components, camelCase for hooks and utilities.
• Formatting: Use Biome for linting and formatting.

---

🤖 Agent Framework specifics

• Core Agents: Orchestrator, Recon, Analysis, Verification.
• Tools: Agents use specialized tools (e.g., sandbox_exec for PoC verification, semgrep_scan, rag_query).
• Sandbox: PoC execution happens in isolated Docker containers (docker/sandbox).
• RAG: Uses ChromaDB for vector storage and Tree-sitter for intelligent code chunking.
• Agent Logic: Implementation resides in backend/app/services/agent/agents/ and tools in backend/app/services/agent/tools/.

📁 Repository Structure

• backend/app/agents/: Agent logic.
• backend/app/api/: API endpoints.
• frontend/src/features/: Frontend modules.
• docker/: Deployment and sandbox configurations.
• rules/: Custom audit rules.