AGENTS.md to let agentic coder better understand project and maintain context across coding sessions.

project_design_expressjs.md

description	globs	alwaysApply
Express.js Project System Design Rules (with Bun)	*.ts *.js	false

Architecture

• Layered Architecture: Implement clean architecture with presentation, business logic, and data access layers
• Modular Structure: Organize into modules that can transition to microservices
• Mono-repo: Use mono-repo for consistent dependency management

Code Quality & Tooling

• Linter: Use eslint with @typescript-eslint for all TypeScript code
• Formatter: Use prettier for code formatting
• Type Checking: Use tsc for type checking
• API Documentation: Use swagger-jsdoc and swagger-ui for API documentation

Project Structure

• API Layer: /src/api - Express routes and controllers
• Domain Layer: /src/domains/{domain} - Business logic and use cases
  • /controllers - HTTP request handlers with validation
  • /services - Business logic layer
  • /repositories - Data access layer
• Infrastructure: /src/infrastructure - Database, external services
• SQL Structure: /sql/queries (TypeScript query builders), /sql/migrations (drizzle/kysely migrations)

Database

• Selection: PostgreSQL (large), SQLite (small/medium), MongoDB (document)
• ORM: Use drizzle-orm or mongoose for database access
• Migrations: Use drizzle-kit or mongoose-auto-migrate for database migrations
• IDs: Use uuid for unique identifiers

Dependencies

• Framework: express for web framework
• DI Container: Use awilix for dependency injection
• Utilities: lodash for utilities, zod for validation
• Auth: jsonwebtoken for JWT authentication
• Mocking: jest or vitest for testing, mock-service-worker for API mocking

Security & Performance

• Security: Rate limiting (express-rate-limit), input validation, HTTPS, structured error handling
• Performance: Implement caching and connection pooling
• Monitoring: Add metrics and health check endpoints
• Configuration: Use dotenv with validation

Testing & Deployment

• Testing: Use jest or vitest for unit/integration tests
• Container Support: Use Docker for containerization
• Runtime: Use Bun for execution and bunx for package management
• Build: Use bun build for production builds

Development Workflow

1. Write database queries with TypeScript query builders
2. Run bun run lint to check code quality
3. Run bun run type-check for type validation
4. Run bun run test to execute tests
5. Run bun run build for production build
6. Run bun run migrate for database migrations

project_design_flutter.md

description	globs	alwaysApply
Flutter Project System Design Rules	*.dart	false

Architecture

• Clean Architecture: MVVM/MVC pattern with clear separation between presentation, business logic, and data layers
• Feature-based Modular: Organize code by features in lib/features/{feature_name}/ structure
• Mono-repo: Use mono-repo for consistent versioning and dependency management

Code Quality & Generation

• Linter: Use flutter_lints + dart_code_metrics with auto-fix
• Code Generation: Use build_runner with injectable for DI and json_serializable for models
• API Documentation: Add Dart doc comments with /// for all public APIs
• Verification: After changes, run: dart pub get && dart pub run build_runner build && flutter analyze && flutter test

File Organization

• Structure: lib/features/{feature}/, lib/core/, lib/data/, lib/presentation/
• Feature Structure: Each feature contains presentation, business_logic, data, and models subfolders
• Testing: test/ for unit/integration tests, test/features/ for feature-specific tests

Database

• Selection: Supabase (cloud), SQLite (local), or Firebase (NoSQL)
• Access: Use drift or sqflite for local, supabase for cloud
• IDs: Use uuid package for unique identifiers
• Transactions: Repository layer handles database transactions

Dependencies

• DI Container: get_it + injectable for dependency injection
• Utilities: collection, rxdart for reactive programming
• State Management: flutter_bloc or riverpod
• Mocking: mocktail for unit tests

Security & Performance

• Security: Input validation, HTTPS, structured error handling
• Performance: Follow Flutter performance optimization patterns
• Monitoring: Add analytics and crash reporting
• Configuration: Environment variables with .env files

Testing & Deployment

• Coverage: Maintain high test coverage with flutter test --coverage
• Multi-platform: Support iOS, Android, Web, and Desktop
• Graceful Handling: Implement proper error handling and state management
• CI/CD: Automated testing, code quality checks, and multi-platform builds

Development Workflow

1. Write models and database schemas
2. Run dart pub run build_runner build to generate code
3. Run flutter analyze to check code quality
4. Run flutter test to execute tests
5. Run flutter build for platform-specific builds

project_design_go.md

description	globs	alwaysApply
Go Project System Design Rules	*.go	false

Architecture

• Clean Architecture with DDD: Implement Domain-Driven Design principles with clear separation between domain, application, and infrastructure layers.
• Modular Monolith: Structure code as a modular monolith, poised for future transition to microservices if needed.
• Mono-repo: Use a mono-repo approach to ensure consistent versioning and dependency management across modules.

Code Quality & Generation

• Linter: Use golangci-lint v2 for all Go code, always applying the --fix flag.
• Interface Mocking: Annotate every interface with //go:generate mockgen -source=$GOFILE -destination=../mock/$GOFILE_mock.go to ensure consistent mock generation.
• Swagger: Ensure all HTTP handlers include @Summary, @Description, and @Router Swagger annotations.
• SQL Generation: Use sqlc to generate type-safe database code from SQL queries defined in the /sql/queries directory.
• Verification: After making changes, execute: go generate ./... && golangci-lint run --fix ./... && go clean -testcache && go test -v -race ./... to verify code correctness and quality.

File Organization

• SQL Structure: Organize SQL code in /sql/queries (for sqlc files) and /sql/migrations (for migrations).
• Domain Structure: Each domain should contain:
  • /interface: Domain interfaces and contracts
  • /handler: HTTP handlers with Swagger docs
  • /usecase: Business logic with dependency injection
  • /repository: Data access using sqlc-generated code
  • /sqlc: Auto-generated SQL code
  • /mock: Generated mock implementations

Database

• Selection:
  • PostgreSQL 18+ for large-scale deployments
  • MariaDB 11+ for small/medium projects
  • FerretDB 2.5+ for document stores
  • Valkey 9+ for key-value storage
• Access: Interact with SQL databases using sqlc for type-safe queries and manage migrations with golang-migrate/migrate.
• IDs: Use UUIDv7 for unique identifiers throughout the system.
• Transactions: Handle database transactions in the repository layer using sqlc-generated code.

Dependencies

• DI Container: Use samber/do for dependency injection.
• Utilities: Use samber/lo for sync helpers and samber/ro for stream processing utilities.
• Auth: Implement authentication with golang-jwt/jwt (primary) or zitadel/oidc (alternative).
• Mocking: Use uber-go/mock and DATA-DOG/go-sqlmock for mocking dependencies in tests.

Security & Performance

• Security: Enforce rate limiting, input validation, HTTPS, and structured error handling in all services.
• Performance: Follow patterns from goperf.dev for optimal performance.
• Monitoring: Implement metrics and health check endpoints for observability.
• Configuration: Use environment variables for configuration, ensuring proper validation.

Testing & Deployment

• Coverage: Maintain high test coverage across all architectural layers.
• Container Support: Ensure all services are compatible with container environments.
• Graceful Shutdown: Implement mechanisms for graceful shutdown of services.
• CI/CD: Integrate automated testing, quality checks, security scanning, and container deployment within your CI/CD pipeline.

Development Workflow

1. Write SQL queries with sqlc comments in /sql/queries.
2. Run go generate ./... to regenerate mocks and SQL code.
3. Run golangci-lint run --fix ./... to fix linting issues.
4. Run go clean -testcache to clear the test cache.
5. Run go test -v -race ./... to execute tests with race detection enabled.

Ambiguity Handling

When the task or provided inputs are ambiguous, ask targeted clarification questions before proceeding rather than guessing.

Tool Boundaries & Argument Validation

Use only tools and utilities specified in these rules. Validate arguments against required formats or tool interfaces before usage. If needed arguments are missing or unclear, request them explicitly rather than making assumptions.

project_design_honojs.md

description	globs	alwaysApply
Hono.js Project System Design Rules (with Bun)	*.ts *.js	false

Architecture

• Clean Architecture: Implement layered architecture with domain separation
• Modular Structure: Organize into modules that can transition to microservices
• Mono-repo: Use mono-repo for consistent dependency management

Code Quality & Tooling

• Linter: Use eslint with @typescript-eslint for all JavaScript/TypeScript code
• Formatter: Use prettier for code formatting
• Type Checking: Use tsc for type checking and vitest for testing
• Swagger: Add JSDoc comments to all API endpoints with OpenAPI specifications

Project Structure

• API Layer: /src/api - Hono handlers and route definitions
• Domain Layer: /src/domains/{domain} - Business logic and use cases
  • /handlers - HTTP handlers with validation
  • /services - Business logic layer
  • /repositories - Data access layer
• Infrastructure: /src/infrastructure - Database, external services
• SQL Structure: /sql/queries (TypeScript query builders), /sql/migrations (drizzle/kysely migrations)

Database

• Selection: PostgreSQL (large), SQLite (small/medium), MongoDB (document)
• ORM: Use drizzle-orm or kysely for type-safe database access
• Migrations: Use drizzle-kit for database migrations
• IDs: Use uuid for unique identifiers

Dependencies

• Framework: hono for web framework
• DI Container: Use inversify or awilix for dependency injection
• Utilities: lodash for utilities, zod for validation
• Auth: lucia-auth for authentication, openid-client for OIDC
• Mocking: vitest with msw for API mocking

Security & Performance

• Security: Rate limiting, input validation, HTTPS, structured error handling
• Performance: Follow Node.js performance best practices
• Monitoring: Add metrics and health check endpoints
• Configuration: Use dotenv with validation

Testing & Deployment

• Testing: Use vitest for unit/integration tests, playwright for E2E tests
• Container Support: Use Docker for containerization
• Runtime: Use Bun for execution and bunx for package management
• Build: Use bun build for production builds

Development Workflow

1. Write database queries with TypeScript query builders
2. Run bun run lint to check code quality
3. Run bun run type-check for type validation
4. Run bun run test to execute tests
5. Run bun run build for production build
6. Run bun run migrate for database migrations

project_design_rust.md

description	globs	alwaysApply
Rust Axum Project System Design Rules	*.rs	false

Architecture

• Clean Architecture with DDD: Implement Domain-Driven Design principles with clear separation between domain, application, and infrastructure layers
• Modular Monolith: Structure code as a modular monolith that can transition to microservices
• Mono-repo: Use mono-repo for consistent versioning and dependency management

Code Quality & Generation

• Linter: Use clippy for all Rust code with -- -D warnings
• Formatter: Use rustfmt for code formatting
• Interface Mocking: Every trait must include #[cfg(test)] mock implementations or use mockall crate
• Swagger: Add OpenAPI documentation to all HTTP handlers using utoipa or axum-extra
• SQL Generation: Use sqlx or diesel for type-safe database code
• Verification: After any changes, run: cargo clippy -- -D warnings && cargo fmt --all && cargo test --lib -- --test-threads=1

File Organization

• SQL Structure: /sql/queries (SQL files), /sql/migrations (database migrations)
• Domain Structure: Each domain contains:
  • /interface - Domain traits and contracts
  • /handler - Axum handlers with OpenAPI docs
  • /usecase - Business logic with dependency injection
  • /repository - Data access using sqlx/diesel
  • /model - Domain models and entities

Database

• Selection: PostgreSQL 15+ (large), SQLite 3.40+ (small/medium), MongoDB 6.0+ (document)
• Access: Use sqlx for type-safe queries, sqlx-cli for migrations
• IDs: Use uuid crate for unique identifiers
• Transactions: Repository layer handles transactions through sqlx transactions

Dependencies

• DI Container: Use async-trait and dependency injection patterns
• Utilities: itertools for iterators, anyhow for error handling, thiserror for custom errors
• Auth: jsonwebtoken for JWT, oauth2 for OAuth2/OIDC
• Mocking: mockall for trait mocking, mockall_double for double mocking
• Async: tokio for async runtime, futures for async utilities

Security & Performance

• Security: Rate limiting, input validation, HTTPS, structured error handling
• Performance: Follow Rust performance best practices, use tokio runtime efficiently
• Monitoring: Add metrics and health check endpoints using metrics crate
• Configuration: Use config crate with environment variables

Testing & Deployment

• Coverage: Maintain high test coverage across all layers using cargo-tarpaulin
• Container Support: All services must support container environments
• Graceful Shutdown: Implement graceful shutdown using tokio::signal
• CI/CD: Automated testing, quality checks, security scanning, container deployment

Development Workflow

1. Write SQL queries with sqlx macros in /sql/queries
2. Run cargo clippy -- -D warnings to check code quality
3. Run cargo fmt --all to format code
4. Run cargo test --lib -- --test-threads=1 to execute tests
5. Run cargo tarpaulin --out Html for test coverage
6. Run cargo build --release for production build

Key Rust-Specific Considerations

• Use Result<T, E> for error handling throughout the application
• Implement proper trait bounds for generic code
• Use async/await patterns consistently
• Leverage Rust's ownership system for memory safety
• Use Arc<Mutex<T>> or RwLock<T> for shared state when needed
• Implement proper error types using thiserror crate
• Use serde for serialization/deserialization
• Follow Rust's naming conventions (snake_case for functions, PascalCase for types)

project_design_spring_boot.md

description	globs	alwaysApply
Spring Boot 4 System Design Rules	*.java *.kt	false

Architecture

• Clean Architecture with DDD: Domain-Driven Design with layered architecture (domain, application, infrastructure)
• Modular Monolith: Modular structure supporting microservices transition
• Mono-repo: Consistent versioning and dependency management

Code Quality & Generation

• Linter: Checkstyle/SpotBugs with Maven/Gradle plugins
• Interface Mocking: Mockito for all interfaces with @MockBean
• API Documentation: SpringDoc OpenAPI with @Operation, @ApiResponse
• Database Access: Spring Data JPA or QueryDSL for type-safe queries
• Verification: mvn clean verify or gradle build with quality gates

File Organization

• SQL Structure: /src/main/resources/db/migration (Flyway), /src/main/resources/sql (queries)
• Domain Structure: Each domain contains:
  • /domain - Domain entities and value objects
  • /application - Use cases and services
  • /infrastructure - Repositories, external integrations
  • /interfaces - REST controllers, DTOs

Database

• Selection: PostgreSQL (large), H2 (dev/test), MySQL (medium)
• Access: Spring Data JPA with Hibernate, Flyway for migrations
• IDs: @GeneratedValue with UUID strategy
• Transactions: @Transactional at service layer

Dependencies

• DI: Spring Framework IoC container
• Utilities: Lombok, Apache Commons
• Auth: Spring Security with JWT
• Testing: JUnit 5, Mockito, Spring Test

Security & Performance

• Security: Spring Security with JWT, input validation, HTTPS
• Performance: Spring caching, async processing, connection pooling
• Monitoring: Actuator endpoints, Micrometer metrics
• Configuration: @ConfigurationProperties with validation

Testing & Deployment

• Coverage: JaCoCo with minimum thresholds
• Container: Docker with multi-stage builds
• Shutdown: @PreDestroy hooks, graceful shutdown
• CI/CD: Maven/Gradle pipelines, quality gates

Development Workflow

1. Define entities and domain models
2. Create repositories with Spring Data JPA
3. Implement services with @Transactional
4. Build REST controllers with validation
5. Write integration tests with Testcontainers
6. Run mvn verify or gradle build
7. Deploy with Docker profiles

rule_memory_bank.md

globs	alwaysApply	description
	true	Agentic AI Coder rules for Nexus, including Memory Bank workflow and general programming guidelines covering performance, concurrency, I/O, error handling, testing, SOLID, and design principles.

Nexus Agentic AI Coder Rules

Nexus acts as an efficient, specification-driven AI engineer with a persistent Memory Bank, applying the programming guidelines defined below to all code by default.

---

1. Role and Style

• Role: Nexus, agentic AI coder and project co-maintainer.
• Style: Concise, direct, actionable.
• No filler. No unnecessary explanation.
• Ask clarifying questions only when essential.

---

2. Memory Bank System

Directory: .agents/rules/memory-bank/

Files Nexus always loads:

The Memory Bank consists of core files and optional context files, all in Markdown format.

Core Files (Required)

1. brief.md This file is created and maintained manually by the developer. Don't edit this file directly but suggest to user to update it if it can be improved.

   • Foundation document that shapes all other files
   • Created at project start if it doesn't exist
   • Defines core requirements and goals
   • Source of truth for project scope

2. product.md

   • Why this project exists
   • Problems it solves
   • How it should work
   • User experience goals

3. context.md This file should be short and factual, not creative or speculative.

   • Current work focus
   • Recent changes
   • Next steps

4. architecture.md

   • System architecture
   • Source Code paths
   • Key technical decisions
   • Design patterns in use
   • Component relationships
   • Critical implementation paths

5. tech.md

   • Technologies used
   • Development setup
   • Technical constraints
   • Dependencies
   • Tool usage patterns

Additional Files

Create additional files/folders within memory-bank/ when they help organize:

1. tasks.md
   • Documentation of repetitive tasks and their workflows
   • Complex feature documentation
   • Integration specifications
   • API documentation
   • Testing strategies
   • Deployment procedures

Nexus must:

• Summarize Memory Bank (3–6 bullets) before major tasks.
• Detect outdated / missing memory.
• Suggest Memory Bank updates whenever decisions change the project.

---

3. Memory Bank Lifecycle

• Initialize → update → refine → validate.
• Update after features, architecture changes, or decisions.
• tasks.md holds workflow templates.

---

4. Command: Initialize Memory Bank

When the user says initialize memory bank:

• Create missing files in .agents/rules/memory-bank/
  (brief.md, product.md, specs.md, architecture.md, context.md, tech.md, tasks.md)
• Do not overwrite existing files without explicit permission.
• Populate using established templates.
• Reload Memory Bank after creation.

---

5. Workflow Modes

Planning

• Provide 3–10 numbered actionable steps.
• Validate against Memory Bank + specs.

Execution

• Follow the plan strictly.
• No scope creep.

Validation

• Check against acceptance criteria.
• Flag unmet requirements.
• Recommend tests.

---

6. Specification-Driven Development

• Specs-first enforcement.
• Propose acceptance criteria when missing.
• Preflight checklist:
  • Specs clear?
  • Constraints known?
  • Memory Bank aligned?
  • Edge cases covered?

---

7. Programming Guidelines (Global Defaults)

Nexus applies these to all code unless the project's tech.md overrides them.

7.1 Performance

• Prefer object/memory pooling in hot paths.
• Preallocate collections to avoid resizing.
• Avoid unnecessary allocations and conversions.
• Minimize heap usage; prefer stack allocation where supported.
• Favor data structures with good cache locality.
• Avoid copying large buffers when zero-copy is possible.

7.2 Concurrency

• Limit concurrency with controlled resource pools.
• Favor atomic operations over locks for simple counters/flags.
• Use lazy initialization for expensive resources.
• Prefer immutable shared data to reduce locking.
• Use cancellation/timeouts for all long-running tasks.

7.3 I/O Efficiency

• Use buffered I/O.
• Batch network or storage operations when possible.
• Use connection pooling for external services.

7.4 General Design & SOLID

• Single responsibility per component.
• Open for extension, closed for modification.
• Subtypes must not break parent expectations.
• Prefer small focused interfaces.
• Depend on abstractions, not concrete implementations.
• Favor composition over inheritance.

7.5 Clean Code Practices

• Keep functions short and focused.
• Avoid global state.
• Use descriptive names.
• Maintain consistent abstractions.

7.6 Error Handling

• Always handle errors explicitly.
• Don't use exceptions for normal control flow unless idiomatic.
• Use typed/structured errors where supported.
• Wrap errors with context and preserve root cause.
• Provide recovery paths when applicable.

7.7 Testing

• Unit-test critical logic.
• Use table-driven / parameterized tests.
• Use mocks/stubs for external dependencies.
• Apply benchmarks for performance-sensitive areas.
• Use property-based tests for generic algorithms.

7.8 Anti-patterns to avoid

• Overusing concurrency without limits.
• Large interfaces that contain too many responsibilities.
• Ignoring error handling.
• Excessive reflection/dynamic runtime typing.
• Tight coupling between modules.
• Premature optimization without profiling.

7.9 Design Patterns (use when appropriate)

• Factory (object creation)
• Strategy (interchangeable algorithms)
• Observer (events)
• Decorator (extend behavior)
• Command (encapsulated operations)
• Template Method (algorithm skeletons)

7.10 Memory Management

• Understand the platform's memory model.
• Minimize object creation in hot paths.
• Use value types where beneficial.
• Ensure proper disposal/cleanup of resources.
• Profile memory usage regularly.

---

8. Long Tasks & Thread Management

• Break large tasks into independent subtasks.
• Suggest Memory Bank updates when appropriate.
• Recommend starting a new conversation when context grows unstable.

---

9. Default Response Structure

1. Summary (2–4 bullets)
2. Plan or steps
3. Output (code, diffs, results)
4. State (impact + Memory Bank update suggestions)

---

10. Minimal / CLI Mode

• Use short responses (~4 lines) when explicitly requested.
• No filler.
• Follow project conventions precisely.

---

11. Safety & Boundaries

• No harmful or malicious code.
• Follow project patterns and style.
• No hidden or silent actions.
• Do not commit without explicit permission.