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

ai_coder.md

globs	alwaysApply	description
	true	AI Coder Unified Ruleset - Enhanced Memory Bank persistence system with comprehensive coding standards, architectural principles, and behavioral guidelines.

Memory Bank System

Location & Files

.agents/rules/memory-bank/

• brief.md - user-only project overview (read-only, requires explicit approval)
• product.md - product goals, UX requirements, feature specifications, roadmap milestones, acceptance criteria
• architecture.md - system architecture, component boundaries, data flows, module interactions, integration points, scalability considerations
• tech.md - technical standards, design patterns, coding conventions, testing frameworks, security requirements, deployment guidelines
• context.md - architectural decisions, domain rules, business logic summaries, file/component summaries, dependency mappings
• tasks.md - operational workflows (test-driven development, refactoring procedures, code review checklists, debugging protocols)

Startup Behavior

1. Load all Memory Bank files in sequence (brief → product → architecture → tech → context → tasks)
2. Print Memory Bank: Active with file count and last modified timestamps OR Memory Bank: Missing with missing files listed
3. Summarize project (3–6 bullets) exclusively from Memory Bank content including: core purpose, architecture type, key technologies, primary features, current state, known constraints
4. Use this context as the single source of truth for all reasoning, planning, and implementation
5. Never scan codebase unless user explicitly approves via written command
6. Validate Memory Bank consistency on load; report any conflicts immediately

Memory Bank Rules

Always reference before: architecture changes, naming conventions, implementation details, coding standards, testing strategies, refactoring operations, code reviews, security considerations, performance optimizations.

Never scan files unless: user commands update memory bank, initialize memory bank, audit codebase, or AI explicitly requests OK to update Memory Bank? and receives confirmation.

Updating rules:

• Extract and preserve long-term knowledge only (no raw code, no ephemeral details)
• Update context.md first (decisions, rules, summaries), then cascade updates to other files as needed
• Ask for confirmation before overwriting major sections (>50 lines) or critical architectural decisions
• Maintain maximum 300 lines per file; use concise summaries and cross-references
• Include timestamps and change rationale for significant updates
• Preserve historical decisions in a decisions_log.md when reversing/changing prior choices

Permissions:

• Editable: context.md, architecture.md, tech.md, product.md, tasks.md (with implicit user trust)
• Read-only: brief.md (requires explicit user approval for any modification)
• Any structural changes to Memory Bank organization require explicit user approval

Thread drift detection:

• Monitor conversation for deviation from Memory Bank context
• Suggest Update Memory Bank and start fresh thread? when contextual relevance degrades
• New thread must reload Memory Bank and confirm alignment before proceeding
• Document thread context gaps when proposing fresh thread

Consistency enforcement:

• All proposals must align with architecture.md, tech.md, product.md, and context.md
• Flag conflicts with user before implementation
• Provide conflict resolution options when guidelines contradict
• Warn on breaking changes and migration requirements

Generic Programming Guidelines

Performance & Concurrency

• Object pooling for frequently allocated/deallocated objects
• Preallocate collections with known capacity when possible
• Optimize cache locality through memory-efficient data structures
• Minimize heap allocations; prefer stack allocation for short-lived objects
• Implement zero-copy patterns where feasible (e.g., string views, slices)
• Use controlled thread/worker pools instead of spawning threads per operation
• Leverage atomic operations for simple state synchronization
• Apply lazy initialization for expensive resources
• Share immutable objects across concurrent operations
• Implement proper cancellation token propagation for long-running operations
• Avoid lock contention; prefer lock-free structures or partitioned locks
• Profile before optimizing; measure performance improvements

I/O & Memory

• Use buffered I/O operations for files, network, and streams
• Batch database operations and bulk writes where possible
• Implement connection pooling for database and network connections
• Understand and respect platform memory models and limitations
• Reduce allocations in hot code paths through object reuse
• Use value types appropriately for performance-critical paths
• Implement proper disposal patterns (IDisposable, RAII, try-with-resources)
• Stream large data rather than loading entirely into memory
• Compress data at rest and in transit where beneficial
• Implement circuit breakers for external service calls

Core Principles

• SOLID Principles:
  • SRP: Single Responsibility Principle - each component has one reason to change
  • OCP: Open/Closed Principle - open for extension, closed for modification
  • LSP: Liskov Substitution Principle - derived types must be substitutable for base types
  • ISP: Interface Segregation Principle - prefer many small, focused interfaces
  • DIP: Dependency Inversion Principle - depend on abstractions, not concretions
• Generics:
  • Leverage generics for type-safe code reuse
  • Apply constraints appropriately to maintain type safety
  • Design generic interfaces for cross-component compatibility
  • Use generic collections with appropriate comparers/equality providers
• Idiomatic Code:
  • Write small, focused functions/methods (single purpose, <50 lines preferred)
  • Use descriptive, self-documenting names (verbs for actions, nouns for entities)
  • Avoid global state; use dependency injection for shared resources
  • Prefer composition over inheritance for behavior reuse
  • Define minimal, focused interfaces that clients actually need
  • Follow language-specific idioms and community conventions
• Error Handling:
  • Handle errors explicitly at appropriate abstraction levels
  • Use typed errors/exceptions with contextual information
  • Wrap lower-level errors with domain-relevant context
  • Implement robust recovery paths where possible
  • Log errors with sufficient detail for diagnosis
  • Distinguish between recoverable and fatal error conditions
  • Avoid silent failures; surface errors explicitly

Testing & Patterns

• Testing Strategy:
  • Unit tests for critical business logic and algorithms
  • Integration tests for component interactions and external dependencies
  • Table-driven tests for multiple input/output scenarios
  • Benchmark tests for performance-critical code paths
  • Use mocks/stubs to isolate units under test
  • Consider property-based testing for data transformation logic
  • Maintain test coverage above 80% for critical paths
  • Tests should be fast, isolated, and repeatable
• Design Patterns (Apply judiciously):
  • Factory: for complex object construction
  • Strategy: for interchangeable algorithms/behaviors
  • Observer: for event-driven notifications
  • Decorator: for extending behavior without inheritance
  • Command: for encapsulating requests/operations
  • Template Method: for algorithm skeleton with customizable steps
  • Builder: for complex object assembly
  • Repository: for data access abstraction
  • Singleton: only when truly required (use dependency injection instead)
  • Adapter: for integrating incompatible interfaces

Anti‑Patterns

• Avoid excessive concurrency that adds complexity without benefit
• Reject god interfaces/classes with too many responsibilities
• Never ignore or silently swallow errors
• Avoid overuse of reflection/dynamic features (type safety preferred)
• Eliminate tight coupling between unrelated components
• Resist premature optimization before measuring actual bottlenecks
• Avoid magic numbers and hardcoded values; use named constants
• Reject copy-paste code duplication
• Avoid feature bloat and over-engineering
• Say no to circular dependencies
• Avoid deep nesting (prefer early returns/guard clauses)

Additional Guidelines

• Design for composition and extensibility from the start
• Use intentional, strong typing to catch errors at compile time
• Maintain clear interface documentation with examples
• Establish and follow consistent naming conventions across codebase
• Prefer pure functions without side effects where appropriate
• Implement proper logging at appropriate abstraction levels
• Follow security best practices (input validation, output encoding, principle of least privilege)
• Make code readable and maintainable; clever code is often maintenance debt
• Use version control effectively with meaningful commit messages
• Document non-obvious design decisions with rationale

Agent Behavior Summary

• Load Memory Bank at the start of every task and use it as the primary context source
• Follow all guidelines above consistently; verify alignment before implementation
• Never read source code files unless explicitly requested by user
• Update Memory Bank only with explicit user authorization
• Warn about contradictions between existing Memory Bank and proposed changes
• Never store raw code in Memory Bank; summarize knowledge only
• Proactively suggest Memory Bank updates when new domain knowledge emerges
• Maintain conversation focus; detect and flag thread drift early
• Provide actionable, specific guidance rather than general advice
• Balance thoroughness with pragmatism; prioritize value over completeness
• When uncertain, ask clarifying questions rather than making assumptions

ai_coder_min.md

globs	alwaysApply	description
	true	AI Coder Unified Ruleset - Memory Bank persistence system replacing full codebase scans.

Memory Bank System

Location & Files

.agents/rules/memory-bank/

• brief.md - user-only project overview (read-only)
• product.md - goals, UX, features, roadmap
• architecture.md - architecture, boundaries, flows, modules
• tech.md - standards, patterns, testing rules
• context.md - decisions, domain rules, file summaries
• tasks.md - workflows (test, refactor, review)

Startup Behavior

1. Load all Memory Bank files
2. Print Memory Bank: Active or Memory Bank: Missing
3. Summarize project (3–6 bullets) from Memory Bank only
4. Use this context for all reasoning
5. Never scan codebase unless user approves

Memory Bank Rules

Always reference before: architecture changes, naming, implementation, coding standards, testing, refactoring, reviews.

Never scan files unless: update memory bank, initialize memory bank, or AI asks OK to update Memory Bank?

Updating rules:

• Extract long-term knowledge only (no raw code)
• Update context.md first, then others as needed
• Ask before overwriting major sections
• Max 300 lines per file

Permissions:

• Editable: context.md, architecture.md, tech.md, product.md, tasks.md
• Read-only: brief.md (needs user approval)

Thread drift: Suggest Update Memory Bank and start fresh thread?; new thread must reload Memory Bank.

Consistency: Enforce with architecture.md, tech.md, product.md, context.md. Confirm conflicts with user + warn.

Generic Programming Guidelines

Performance & Concurrency

• Pool objects, preallocate collections, optimize cache locality
• Minimize heap, prefer stack, zero-copy when possible
• Controlled pools, atomic ops, lazy init, immutable sharing, cancellation tokens

I/O & Memory

• Buffered I/O, batch ops, connection pooling
• Know platform model, reduce hot-path allocations, use value types, dispose properly

Core Principles

• SOLID: SRP, OCP, LSP, ISP, DIP
• Generics: type-safe reuse, constraints, interfaces, collections
• Idiomatic: small focused functions, descriptive names, no globals, composition over inheritance, minimal interfaces
• Error handling: explicit handling, typed errors, wrap context, robust recovery

Testing & Patterns

• Unit tests critical logic, table-driven tests, benchmarks, mocks/stubs, property-based tests
• Patterns: Factory, Strategy, Observer, Decorator, Command, Template Method

Anti‑Patterns

• Excessive concurrency, god interfaces, ignored errors, overuse of reflection/dynamic, tight coupling, premature optimization

Additional

• Design for composition/extensibility, intentional strong typing, clear interface docs, consistent conventions

Agent Behavior Summary

• Load Memory Bank every task, use as primary context
• Follow all guidelines above, ensure consistency
• Never read source unless asked, update Memory Bank only with authorization
• Warn contradictions, never store raw code