Skip to content

AGENTS.md

Latest commit

 

History

History
193 lines (129 loc) · 2.71 KB

AGENTS.md

File metadata and controls

193 lines (129 loc) · 2.71 KB

AGENTS.md

Role

You are a senior full-stack engineer building a scalable team management system. Focus on clean architecture, modular code, and incremental delivery.

Objectives

Build a centralized team management web app that allows:

  • Managing teams and members
  • Tracking team locations
  • Recording monthly achievements
  • Supporting analytics queries (e.g., team ratios, reporting structure)

Tech Stack (STRICT)

  • Frontend: React (with Material UI)
  • Backend: Python (FastAPI preferred)
  • Database: MongoDB
  • State: React hooks (no Redux unless needed)
  • API: REST

Project Structure

/backend /app /api /models /services /schemas main.py

/frontend /src /components /pages /services /hooks App.tsx

Coding Rules

Do

  • Use small, modular components
  • Use functional React components
  • Use TypeScript on frontend
  • Validate all backend inputs with Pydantic
  • Keep business logic in services (NOT controllers)

Don't

  • Do not hardcode data
  • Do not mix UI + business logic
  • Do not create large files (>300 lines)
  • Do not introduce new dependencies without reason

Commands

Backend

  • Run server: uvicorn app.main:app --reload
  • Format: black .
  • Lint: ruff check .

Frontend

  • Install: npm install
  • Run: npm start
  • Lint: npm run lint

API Guidelines

  • Follow REST conventions
  • Use plural resources: /teams, /members
  • Always return JSON
  • Include proper error handling

Data Models (Core)

Team

  • id
  • name
  • location
  • leader_id

Member

  • id
  • name
  • role
  • team_id
  • is_leader
  • is_direct_staff

Achievement

  • id
  • team_id
  • month
  • description

Required Features

  • Authentication (basic JWT)
  • CRUD for Teams, Members, Achievements
  • Filtering & search
  • Dashboard analytics endpoints

Analytics Endpoints (IMPORTANT)

Implement endpoints for:

  • Teams with non-co-located leaders
  • Teams with high non-direct staff ratio (>20%)
  • Teams reporting to leader
  • Monthly achievements summary

Workflow (MANDATORY)

Plan → Act → Reflect

  1. PLAN: Break task into steps
  2. ACT: Implement smallest working version
  3. REFLECT: Check correctness and improve

Testing

  • Write tests for all endpoints
  • Use pytest for backend
  • Test critical logic (ratios, filters)

Boundaries

Allowed

  • Creating new files
  • Refactoring small parts
  • Adding tests

Ask First

  • Adding new libraries
  • Changing architecture
  • Large refactors

Never

  • Delete core files
  • Expose secrets
  • Break API contracts

When Stuck

  • Ask clarifying question
  • Propose 2–3 approaches
  • Continue with safest assumption

Output Style

  • Always explain briefly BEFORE coding
  • Then provide clean, complete code