agenticCode/CLAUDE.md

AgenticCode

0. Hard Rules

• NEVER ask questions in response text. Every question to the user MUST go through the AskUserQuestion tool. No exceptions. If you need to ask something, use AskUserQuestion. If you need clarification, use AskUserQuestion. If you need a decision, use AskUserQuestion. The tool provides a freetext option automatically — use it.
• Never assume anything about the user's intent. Ask questions and wait for the user to clarify.
• Always use agentic code see x-docs/agent-api-usage-ac-implementation.md to understand the code, get an overview and if somethinmg is missing or not working, report it directly. Also. find identifier via agentic code. if agentic code is not running, report it.
• NEVER start Docker yourself — the human starts it. If you need the server/Neo4j for analysis and http://localhost:8787 is unreachable, stop and ask the user to run ./manage-ac.sh deploy (via AskUserQuestion, per the rule above). Do not run ./manage-ac.sh deploy, docker compose up/start/restart, or otherwise bring containers up on your own initiative — not to "just check something", not because it is faster. Starting the stack is the human's call, like committing. The same goes for stopping or restarting it: ask first. You may read container state (docker ps, logs) freely.
• Clean up what you start. Any long-running probe you launch (cypher-shell, background Bash, a query against Neo4j) must be stopped before you report done. TaskStop kills the client, not the JVM behind a docker exec — verify with ps on the host and inside the container, then say so. Never report "all shells stopped" from the task list alone.
• If agentic code is not ingested, refresh it again (ac refresh / POST /api/projects/ac/refresh)
• After implementation do a refresh again to get the latest changes.
• A deep refresh is long and mutates the graph. Do not abort one halfway: the earlier enrichment steps are already committed, so the graph is left partially updated and every later query silently answers from it. If one must be stopped, say plainly that the graph is now in a half-updated state.
• Keep the REST API and ac-cli in sync. Every REST endpoint added or changed in ac-code-server/.../api/*Resource.java MUST have a matching ac-cli command, delivered in the same change. Treat REST + CLI as one unit of work — neither is "done" without the other.

1. Core Rules

• Never assume. Always read files first with tools.
• Make all assumptions explicit and visible.
• Prioritize good structure, modularization, and maintainability.
• Keep solutions simple — only as abstract as necessary.
• Validate state before and after changes using terminal commands.
• Remove dead/unreachable code immediately (ask first if unsure).
• Be willing to backtrack if heading in the wrong direction.
• Trivial tasks: Ask "Trivial? Direct edit or full workflow?"
• Never run git commit (or git push) without the user explicitly asking for it in that turn. A prior commit approval does not carry over to later changes.
• The human decides what to commit and when. Committing is a human decision, not yours. Do not stage, group, or propose commits on your own initiative, and do not nudge toward committing. You may prepare a suggested commit message when asked, but the act — and its timing and scope — is the human's call alone.
• All features must be tracked in x-docs/roadmap.md. Once a feature has been implemented, mark it [x] and add a timestamp (date) indicating when it was completed.
• For every feature that changes API behavior or what an agent can query, you MUST update x-docs/agent-api-usage-ac-implementation.md to reflect it (new/changed endpoints, response fields, semantics) — treat this doc update as part of the feature's Definition of Done, not an optional follow-up.
• Never add a Co-Authored-By: line (or any AI-attribution trailer) to commit messages.
• Dogfooding: use AgenticCode itself for static analysis of this repo whenever possible. The server runs at http://localhost:8787 with this repo already ingested as project ac. Prefer it over grep/Explore for call graphs, callers/callees, DB access, dataflow, and module overviews — it's exactly the tool this project builds, so using it here is both faster and the best test of its own output. Usage guide: x-docs/agent-api-usage-ac-implementation.md. Re-ingest after code changes (ac refresh / POST /api/projects/ac/refresh, or --deep/?deep=true for a full field-level pass) before trusting query results.
  • Tool priority: REST API first, then the ac CLI, then grep/Explore. Query the REST endpoints (GET /api/projects/ac/modules/{name}/...) before anything else. The ac <command> CLI (ac callers, ac callees, ac call-tree, ac context, ac db-accesses, ac refresh, ...) is a convenience wrapper over the same REST API, useful for quick manual checks. If the server is unavailable (http://localhost:8787 unreachable), ask the user to run ./manage-ac.sh deploy — never start it yourself (see Hard Rules). Only when it still can't answer the question (info the API doesn't expose, or the analysis needs exact source text/comments/formatting) fall back to normal code analysis (Read/Grep/Explore agent) exactly as you would on any other codebase.
  • If a needed capability is missing from the API/CLI (not just unreachable, but the question is one none of them can answer at all), don't silently fall back to grep and move on — after finishing the task with the grep-based fallback, use AskUserQuestion to tell the user what was missing and ask whether it should be added as a feature in x-docs/roadmap.md.

2. Mandatory 4-Phase Workflow

``0. Clarify Intent -Assess if the user's request is fully clear. - Clear: State your understanding and proceed. - Unclear: Use AskUserQuestion tool with concrete options. Repeat until unambiguous.

1. PROPOSAL – Clear plan + impact. Wait for OK PROPOSAL.
2. VALIDATE – Brutal self-critique (NullAway, layering, regressions). Wait for OK VALIDATE.
3. IMPLEMENT – One unit at a time. Show exact diff only.
4. VERIFICATION – Run relevant tests. Suggest a commit message, but do not commit unless asked (see Core Rules).``

Quarkus-based server for parsing, storing, and agentically querying source code (Natural/Software AG and Java). Programs are parsed into a unified AST, persisted as a graph in Neo4j, enriched with semantic information, and exposed via an agent-optimized API.

Architecture Overview

Parser Layer  →  Unified AST  →  Neo4j Graph DB  →  Enrichment  →  Agentic API (REST)

• Natural Parser: custom implementation (no OSS parser available for Software AG Natural)
• Java Parser: JavaParser library
• Graph Store: Neo4j — nodes for modules, functions, variables, data structures, DB accesses
• Enrichment: call graph, identifier index, data structures, ADABAS/SQL access patterns
• API: Quarkus REST (JAX-RS), optimized for AI agent tool use

Tech Stack

Component	Technology
Server	Quarkus (latest stable)
Language	Java 21 (Virtual Threads enabled)
Graph DB	Neo4j 5.x (via neo4j-java-driver)
REST	Quarkus RESTEasy Reactive (JAX-RS)
JSON	Jackson (quarkus-jackson)
Natural Parser	Custom impl in ac-parser-natural module
Java Parser	JavaParser (com.github.javaparser)
Tests	JUnit 5 + RestAssured + Testcontainers (Neo4j)
Build	Maven (multi-module)
Config	application.properties (dev/prod profiles)

Project Structure

agenticcode/
├── CLAUDE.md
├── pom.xml                          # Root POM (multi-module)
├── ac-code-server/                      # Quarkus application
│   ├── src/main/java/de/agenticcode/
│   │   ├── api/                     # JAX-RS Resources
│   │   ├── service/                 # Business logic
│   │   └── enrichment/              # Enrichment pipelines
│   └── src/main/resources/
│       └── application.properties
├── ac-parser-natural/                  # Natural parser module
│   └── src/main/java/de/agenticcode/parser/natural/
├── ac-parser-java/                     # Java parser module
│   └── src/main/java/de/agenticcode/parser/java/
├── ac-parser-core/                     # Shared AST schema + interfaces
│   └── src/main/java/de/agenticcode/ast/
│       ├── model/                   # AstNode, AstEdge, NodeType, EdgeType
│       └── spi/                     # LanguageParser interface
├── ac-neo4j-store/                     # Neo4j persistence + queries
│   └── src/main/java/de/agenticcode/graph/
└── docs/
    ├── ast-schema.md                # Neo4j node/edge types with Cypher examples
    ├── natural-grammar.md           # Natural language constructs and parser decisions
    ├── api-endpoints.md             # Full API reference
    └── enrichment-pipelines.md      # Enrichment logic and pipeline design

Build & Run

Maven settings: .mvn/maven.config (gitignored, machine-local) points -s at ~/.m2/settings_my.xml — the working repository configuration, since the default Maven settings point at an internal artifactory not reachable from this environment. Plain mvn ... picks it up automatically; no need to pass -s explicitly.

# Full build
mvn clean install

# Dev mode (hot reload)
cd ac-code-server && mvn quarkus:dev

# Native build (GraalVM)
mvn package -Pnative

# Run all tests (includes Testcontainers Neo4j)
mvn test

# Test a single module
mvn test -pl ac-parser-natural

Requirements: Java 21+, Maven 3.9+, Docker (for Testcontainers).

# Start Neo4j locally for dev — for the human to run, not the agent (see Hard Rules)
docker run -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/agenticcode \
  neo4j:5

Code Conventions

General

• Use Java 21 features: Records for DTOs/value objects, Sealed Classes for AST node types, Pattern Matching
• Non-null is the default (enforced by NullAway, packages annotated @NullMarked). Avoid Optional for fields, parameters, and most return types — use @org.jspecify.annotations.Nullable only where a value can genuinely be absent. Prefer empty collections over Optional<List<T>>.
• Immutable by default: prefer Records over mutable classes
• Logging: org.jboss.logging.Logger (Quarkus standard) — no System.out

Naming

• Packages: com.agenticcode.<module>.<layer> (all lowercase)
• Parser classes: NaturalParser, JavaParser (implement LanguageParser)
• API classes: ModuleResource, AnalysisResource (JAX-RS Resources)
• Service classes: AstIngestService, CallGraphService, EnrichmentService
• Neo4j classes: GraphRepository, CypherQueryBuilder

Quarkus Specifics

• CDI: @ApplicationScoped for services, @RequestScoped for stateful request context
• All configuration via @ConfigProperty — never hardcoded values
• Reactive where appropriate: Uni<T> / Multi<T> (Mutiny) for Neo4j calls
• Implement health checks: @Liveness, @Readiness

AST / Graph

• Node types are defined as enum NodeType in ac-parser-core — never use raw strings
• Edge types are defined as enum EdgeType in ac-parser-core — never use raw strings
• Every node must have: id (UUID), sourceFile, language, startLine, endLine
• Cypher queries do not belong inline in service classes — put them in a CypherQueries constants class

Unified AST Schema (Neo4j)

Node types (NodeType enum):

• MODULE — a Natural source file or Java class
• FUNCTION — Natural subroutine or Java method
• VARIABLE — local variable or parameter
• DATA_STRUCTURE — Natural DEFINE DATA block or Java DTO
• DB_TABLE — ADABAS view or SQL table

Edge types (EdgeType enum):

• CONTAINS — module contains function
• CALLS — function calls another function (call graph)
• READS / WRITES — function reads/writes a variable or DB table
• USES_TYPE — function or variable references a data structure

Full schema with Cypher examples: @docs/ast-schema.md

API Design Principles

The API is designed primarily for AI agent tool use:

• Responses are concise and machine-readable JSON
• Each endpoint does exactly one thing — no overloading
• Errors return structured JSON: { "error": "...", "code": "...", "details": {} }
• Pagination via limit + offset (default: limit=50)
• Priority endpoints to implement first:
  • GET /api/modules/{name}/callers — who calls this module?
  • GET /api/modules/{name}/callees — what does this module call?
  • GET /api/modules/{name}/db-accesses — DB tables and access mode (READ/WRITE)
  • GET /api/search/identifier?name=... — find an identifier across all modules
  • POST /api/ingest — parse and ingest source code into the graph

Endpoint structure: @docs/api-endpoints.md

Natural Parser: Key Constructs

When implementing or extending NaturalParser, always use @ac-parser-natural/src/main/resources/natural-grammar.md as the authoritative reference for Natural language syntax, statement variants, and edge cases.

The following Natural language constructs must be recognized (priority order):

1. DEFINE DATA LOCAL/PARAMETER/GLOBAL — data structure declarations
2. PERFORM <subroutine> — internal subroutine call (call graph)
3. CALLNAT '<module>' — external module call (call graph)
4. READ/FIND/STORE/UPDATE/DELETE ... <view> — ADABAS DB access
5. DEFINE SUBROUTINE / END-SUBROUTINE — function boundaries
6. IF/ELSE/END-IF, FOR/END-FOR, REPEAT/END-REPEAT — control flow
7. MOVE, ASSIGN, COMPUTE — variable assignments

Parser decisions and edge cases: @docs/natural-grammar.md

Enrichment Pipelines

Enrichment runs as a separate phase after ingest:

Ingest → AST in Neo4j → EnrichmentPipeline.run() → enriched edges + properties

• CallGraphEnricher: resolves PERFORM/CALLNAT → CALLS edges
• DbAccessEnricher: extracts READ/FIND/STORE → READS/WRITES edges to DB_TABLE
• IdentifierIndexEnricher: indexes all variable nodes for cross-module search
• DataStructureEnricher: links DEFINE DATA blocks to the functions that use them

All enrichers implement de.agenticcode.enrichment.spi.GraphEnricher (single enrich(String moduleId) method).

Details: @docs/enrichment-pipelines.md

Testing

• Unit tests: pure Java logic, no container, no Neo4j
• Integration tests: @QuarkusTest + Testcontainers Neo4j (annotated @NaturalParserIT)
• Parser tests: fixture files in src/test/resources/fixtures/natural/ and .../java/
• No Thread.sleep() in tests — use Awaitility

# Unit tests only
mvn test -Dtest="*Test"

# Integration tests only
mvn test -Dtest="*IT"

Key Decisions (ADR Summary)

Decision	Rationale
Quarkus over Spring	Native build support, fast startup, CDI standard
Neo4j over relational DB	Call graphs and traversals are naturally graph problems
Multi-module Maven	Parsers are independently testable and replaceable
Custom Natural parser	No OSS parser available for Software AG Natural
JavaParser over tree-sitter	Mature Java library, type-safe AST API