Skip to content

AGENTS.md

Latest commit

 

History

History
51 lines (39 loc) · 7.6 KB

AGENTS.md

File metadata and controls

51 lines (39 loc) · 7.6 KB
Raw

Nexent project instructions

Repository map

  • backend/ contains the FastAPI HTTP API; sdk/nexent/ contains the agent framework.
  • frontend/ contains the Next.js UI. Deployment resources live in deploy/, docker/, and k8s/.
  • Python tests live in test/backend/ and test/sdk/.

Shared constraints

  • Write code comments, docstrings, TODOs, and configuration comments in English. User-facing strings may use supported languages; this does not prescribe conversation language.
  • Every new or modified source file (.py, .sh, .sql, .ts, .tsx, .js, .jsx, .mjs) must start with the copyright header Copyright (c) 2025-2026 Huawei Technologies Co., Ltd. All rights reserved. (the end year tracks the current year, e.g. 2025-2027 in 2027) in the file's comment style (# for Python/Shell, -- for SQL, // for TypeScript/JavaScript), placed after shebang/encoding lines. The Copyright Header Check CI job rejects changed files missing it; verify or fix locally with python scripts/check_copyright.py [--fix] <files...>.
  • In backend/SDK Python code, centralize environment reads in backend/contracts/constants/environment.py. Backend callers import from contracts.constants.environment; SDK code accepts parameters and must not read environment variables or introduce from_env() methods.
  • Every SQL file under deploy/sql/ already merged into the target branch is immutable, including initialization and Supabase SQL. Do not edit, rename, or delete it. Add versioned migrations under deploy/sql/migrations/; application version is APP_VERSION in backend/contracts/constants/environment.py.
  • Preserve existing HTTP routes, payloads, and response contracts when applying conventions to new code.

Load rules for the task

Before editing or reviewing these areas, read the linked skill and only its applicable references. Paths are relative to this root. Read files directly if the client has no skill loader; no package download is required. For cross-layer work, load each relevant skill. Documentation-only work does not require unrelated coding skills.

Task or affected area Entry point
Backend endpoints, services, database access, backend/SDK configuration, SQL migrations .agents/skills/nexent-backend/SKILL.md
Frontend pages, UI, hooks, API services, types, styles, localization .agents/skills/nexent-frontend/SKILL.md
Requirement or bug lifecycle, SPEC traceability, and delivery gates .agents/skills/nexent-spec-coding/SKILL.md
Requirement-driven Feature catalog, D1-D5 case-local tests and bindings, generated registry and Excel view under test-e2e/ .agents/skills/nexent-test-assets/SKILL.md
Python unit tests for every product change: unit behavior, boundaries, errors and regressions .agents/skills/nexent-python-tests/SKILL.md

These Markdown files are the maintained rules. .cursor/rules/ contains compatibility entry points with the original Cursor triggers. Edit canonical rules when changing policy. See migration decisions when maintaining this setup.

Development and verification

  • Traditional UT and formal D1-D5 are permanently separate, complementary suites. Every product-code change must assess both; implement or reuse applicable UT and formal Cases. Do not manufacture edits or a five-stage quota. Non-behavior-only changes may use an explicit documented exemption; missing prerequisites are blockers, not exemptions.
  • Before submitting a product-code PR, run relevant traditional UT locally. New/changed behavior needs success, boundary and error assertions; bugfixes need a regression that detects the defect (reuse is valid when demonstrated). PR CI must run its configured UT set; required-check enforcement belongs to GitHub branch protection and is not established by these instructions. Do not change workflows or remote protection without authorization.
  • Preserve all existing D1 Cases and scripts; overlap with UT is not grounds for deletion, retirement or relabeling. New D1 should prove a component contract with real internal collaboration and controlled external boundaries; D3 proves inter-component/service/protocol runtime integration. Choose by proof boundary, not function calls or mocks. Use no extra layer when it adds no necessary evidence.
  • Before adding new D1, inspect actual existing UT/formal inputs and assertions, record the remaining gap and additional component evidence, and apply nexent-test-assets' admission rules. A Feature needs no D1 quota; sufficient unit proof stays in UT. For code already developed, use its test-backfill mode rather than generating a Case per function or restarting development. Preserve required higher-boundary checks.
  • Keep traditional UT results/coverage separate from formal functional results; frontend and Python coverage percentages are never combined. A collected script passing is not evidence that every written acceptance requirement was implemented. Record acceptance implementation gaps and distinguish execution from completeness.
  • Backend setup uses Python 3.11. From backend/, run uv sync --extra data-process --extra test; this includes the editable local nexent[dev] distribution (Python imports remain nexent). Add --index pytorch-nvidia --upgrade-package torch --upgrade-package torchvision for CUDA 13.0; select pytorch-cpu with the same upgrade flags to switch back. Both variants use the same extra. Use uv 0.13.6.
  • Run targeted tests from the root using the configured backend environment, for example pytest test/backend/apps/test_agent_app.py -v. The broader runner is python test/run_all_test.py. Confirm the interpreter works before testing.
  • Formal D1-D5 assets live in test-e2e/; use python test-e2e/infra/tools/validate_test_assets.py --phase implementation to check generated views and python test-e2e/infra/tools/run_cases.py <Case-ID> --test-home <local-test-data> for targeted execution. Keep machine-local configuration and results outside Git.
  • For added/changed formal assets, follow nexent-test-assets' preparation/delivery gate: confirm responsibility routing, declare active automated D2-D5 preparation (including justified self-contained empty families), and verify owned cleanup. Reconcile the current target branch and repeat strict validation before delivery/merge; record the tested revision and actual preparation-test-cleanup evidence.
  • From frontend/, npm run dev starts development. npm run check-all runs type-check, lint, format checking, and build; individual checks are in frontend/package.json.
  • Match verification to changed behavior and report checks actually run or blocked. For instruction-only edits, validate paths, skill metadata, scope, and rule coverage; application suites are unnecessary.
  • Python imports follow standard library, third-party, then project order. SDK Ruff configuration uses a 119-character line limit.

Docker compatibility

  • Support Docker Engine 18.09 / API v1.39; the Compose CLI may be current.
  • Newer daemon capabilities, including GPU device requests, cgroup namespace modes, and healthcheck start_interval, require an Engine version check and an 18.09-compatible fallback.
  • Quote boolean-like and numeric values in Compose environment mappings. Schema boolean fields such as privileged and external remain booleans.
  • Inspect current deployment scripts and deploy/env/.env.example for deployment work. Deployment execution remains limited to the user's authorized scope.