Skip to content

CLAUDE.md

Latest commit

 

History

History
66 lines (51 loc) · 4.44 KB

CLAUDE.md

File metadata and controls

66 lines (51 loc) · 4.44 KB
Raw

AsterixDB

Apache AsterixDB — the BDMS query engine, storage layer, and Hyracks distributed runtime. See README.md for an overview.

The tree has two roots:

  • asterixdb/ — the AsterixDB engine (SQL++ compiler, external data, cloud, storage).
  • hyracks-fullstack/ — the Hyracks runtime and shared utilities (hyracks-util, hyracks-cloud, etc.).

Files here carry the Apache license header (see README.md). Preserve it when editing or creating files.

AI Provenance Annotation

When you (an AI agent) generate or assist with Java code in this tree, annotate it with @AiProvenance. This records which model and tool produced the code so the contribution is auditable. The annotation is defined here, in this repository.

  • Annotation: org.apache.hyracks.util.annotations.AiProvenance — source at hyracks-fullstack/hyracks/hyracks-util/src/main/java/org/apache/hyracks/util/annotations/AiProvenance.java. It is on the classpath of every module that depends on hyracks-util (effectively all of them).
  • @Retention(SOURCE) — documentation only; stripped at compile time, so no runtime or bytecode cost. The repeatable container @AiProvenances is RUNTIME-retained for tools that scan class files.
  • Applies to: types, methods, constructors, fields, and local variables.

Attributes

Attribute Required Values
agent yes AiProvenance.Agent — the model that did the work (e.g. CLAUDE_OPUS_4_8, CLAUDE_SONNET_4_6, GPT_5_MINI)
tool yes AiProvenance.Tool — the invocation surface (e.g. CLAUDE_CODE_UI, CLAUDE_CODE_CLI, GITHUB_COPILOT)
contributionKind no (default GENERATED) GENERATED, ASSISTED, REFACTORED, TEST_GENERATED, DOC_GENERATED
notes no free-text, e.g. what changed or why

How to inject it

  1. Pick the narrowest element that captures the AI contribution: annotate the type only when the whole class is AI-authored. When AI adds or rewrites individual methods (or a field/constructor) within an otherwise human-authored class, annotate each of those methods — do not promote the annotation to the type level.
  2. Match agent to the model actually used. When the author is Claude Code (the Code tab in the Claude app / the claude CLI), use agent = AiProvenance.Agent.CLAUDE_OPUS_4_8 (the current model — update if running a different one) and tool = AiProvenance.Tool.CLAUDE_CODE_UI. For the claude.ai chat web app use CLAUDE_CODE_UI; for Copilot-in-IDE use GITHUB_COPILOT.
  3. Choose contributionKind honestly: GENERATED (from scratch), ASSISTED (human-led, AI-suggested), REFACTORED (rewriting existing code), TEST_GENERATED, DOC_GENERATED.
  4. Stack annotations (it is @Repeatable) to record history — e.g. generated by one model then refactored by another.
  5. Import style: either static-import the constants for brevity, or import the type and qualify (AiProvenance.Agent.X). Both are used in-tree.

Example

In-tree usages include asterixdb/asterix-external-data/.../aws/s3/S3Utils.java, asterixdb/asterix-cloud/.../S3TrustManagerProvider.java, and hyracks-fullstack/hyracks/hyracks-util/.../Span.java.

import org.apache.hyracks.util.annotations.AiProvenance;

@AiProvenance(agent = AiProvenance.Agent.CLAUDE_OPUS_4_8, tool = AiProvenance.Tool.CLAUDE_CODE_UI,
        contributionKind = AiProvenance.ContributionKind.GENERATED, notes = "Initial implementation")
public final class ExampleHelper { ... }

If a model you used is missing from the Agent/Tool/Provider enums, add it to AiProvenance.java rather than falling back to OTHER.