117 lines (79 loc) · 2.13 KB

AGENTS.md

ResiGraph Development Guidelines

Core Rules

Write clean, maintainable, production-quality code.
Follow clean architecture and SOLID principles.
Make minimal changes. Do not modify unrelated parts of the codebase.
Prefer simple, readable, and extensible solutions.
Avoid unnecessary dependencies and premature optimization.

Architecture

Maintain clear separation between:

API layer
Service layer
Domain layer
Repository/Storage layer
Infrastructure layer

Rules:

Keep business logic out of API routes.
Avoid direct coupling to external libraries.
Use abstractions when components may change in the future.

Code Quality

Use meaningful names for classes, functions, variables, and tests.
Add English docstrings to all public classes and functions.
Use type hints everywhere.
Prefer structured models over raw dictionaries.
Handle errors explicitly.
Use project logging instead of print().

Testing

Every new feature must include tests.

Tests should cover:

Normal behavior
Edge cases
Invalid inputs
Error handling

Test names must describe behavior.

Example:

test_query_engine_returns_related_concepts_with_evidence()

Configuration

Do not hardcode runtime values.
Use configuration files or environment variables.
Keep model, path, and runtime settings configurable.
Python commands: In this development environment, always use python3 in shell commands. Never use bare python.

Documentation

When adding features:

Update relevant documentation.
Keep examples accurate.
Document important design decisions.

Git

Keep commits focused and descriptive.

Preferred:

feat(graph): add graph query engine
fix(llm): handle inference timeout

Avoid:

update files
fix stuff
changes

Completion Checklist

Before finishing any task: