NornicDB AGENTS.md

NornicDB Development Guide for AI Agents

Version: 1.0.0
Last Updated: 2024-12-01
Target Audience: AI coding agents (Claude, GPT-4, etc.)

---

Core Philosophy

NornicDB is an enterprise-grade, high-performance graph database that prioritizes:

1. Neo4j Compatibility - Drop-in replacement with zero code changes
2. Performance - 3-52x faster than Neo4j across benchmarks
3. Correctness - 90%+ test coverage, regression prevention mandatory
4. Maintainability - Clean architecture, separation of concerns, DRY principles
5. Documentation - Every public API fully documented with real-world examples

---

🎯 Golden Rules

1. Prove Value Before Merging

Every change must demonstrate measurable improvements without significant regressions:

• Performance: Benchmark before/after. Show ops/sec improvements.
• Memory: Profile memory usage. No >10% increases without justification.
• Code Quality: Maintain or improve test coverage (90% minimum).
• Compatibility: All Neo4j compatibility tests must pass.

Example:

// ❌ BAD: No proof of improvement
func optimizeQuery() { /* new algorithm */ }

// ✅ GOOD: Benchmarked and documented
// BenchmarkQueryOptimization shows 2.3x speedup:
//   Before: 4,252 ops/sec
//   After:  9,780 ops/sec
//   Memory: -15% (reduced allocations)
func optimizeQuery() { /* new algorithm with proof */ }

2. Test-Driven Bug Fixes

MANDATORY WORKFLOW for all bugs:

1. Write failing test - Reproduce the exact bug condition
2. Verify test fails - Confirm it catches the bug
3. Fix the bug - Implement minimal fix
4. Verify test passes - Confirm fix works
5. Add regression tests - Prevent future occurrences

Example from codebase:

// File: pkg/cypher/aggregation_bugs_test.go
// BUG #1: WHERE ... IS NOT NULL combined with WITH aggregation returns empty results

func TestBug_WhereIsNotNullWithAggregation(t *testing.T) {
    // 1. Setup test data that triggers bug
    setupAggregationTestData(t, store)
    
    // 2. Execute query that fails in production
    result, err := exec.Execute(ctx, `
        MATCH (f:File)
        WHERE f.extension IS NOT NULL
        WITH f.extension as ext, COUNT(f) as count
        RETURN ext, count
    `, nil)
    
    // 3. Assert expected behavior (this WILL fail before fix)
    require.NoError(t, err)
    assert.Equal(t, int64(2), extCounts[".ts"])
    assert.Equal(t, int64(3), extCounts[".md"])
}