feat: add AGENTS.md files for agentic tools across language bindings #4739

jbrinkman · 2025-09-16T12:59:54Z

Summary

Adds comprehensive AGENTS.md files to provide AI agents and developers with the minimum but sufficient context to work productively in the Valkey GLIDE repository and its language bindings.

Changes

Root Repository

/AGENTS.md - Unified context for the mono-repo covering all language bindings, build system, and cross-language development

Language Bindings

/java/AGENTS.md - Java client context (Gradle, JNI, platform classifiers, Spotless/SpotBugs)
/node/AGENTS.md - Node.js client context (npm, TypeScript, NAPI-RS, async frameworks)
/python/AGENTS.md - Python client context (async/sync clients, dev.py CLI, PyO3/CFFI)
/go/AGENTS.md - Go client context (Make targets, CGO, cross-compilation)
/java/jedis-compatibility/AGENTS.md - Jedis compatibility layer context (drop-in replacement API)

Content Structure

Each AGENTS.md file includes:

Repository/component overview and architecture
Build and test commands (preferred targets + raw equivalents)
Contribution requirements (DCO signoff, conventional commits)
Code quality requirements (linters, formatters)
Guardrails and policies (generated outputs, security)
Project structure overview
Quality gates checklist
Quick facts for AI reasoners
Links to additional documentation

Key Features

Accurate Commands: All build/test commands extracted from actual Makefiles, package.json, build.gradle files
Platform-Specific: Includes Alpine/MUSL, platform classifiers, cross-compilation guidance
Language-Specific: Respects each language's conventions while maintaining consistency
AI-Optimized: Structured format designed for both human and AI agent consumption
Actionable: Quality gates provide clear pass/fail checklists

Benefits

Improved Developer Experience: Clear, actionable guidance for contributors
Consistent Contribution Process: Standardized requirements across all language bindings
Reduced Onboarding Time: Essential context in single, skimmable documents
AI Tool Compatibility: Optimized for AI-powered development tools
Quality Assurance: Clear checklists prevent common contribution issues

Testing

All commands verified against actual build configurations
Files follow repository conventions and existing documentation patterns
Content extracted from authoritative sources (Makefiles, package configs, etc.)

Closes #4738

yipin-chen

Node and Python LGTM

AGENTS.md

jamesx-improving

LGTM for the go document, assuming all comments addressed

go/AGENTS.md

node/AGENTS.md

* Go: Switch to MUSL binary Signed-off-by: James Xin <james.xin@improving.com> Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * rustup add musl targets Signed-off-by: James Xin <james.xin@improving.com> Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * lint Signed-off-by: James Xin <james.xin@improving.com> Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * rustup add musl targets in Makefile Signed-off-by: James Xin <james.xin@improving.com> Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Add pathing Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Trigger CodeQL on main Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Update CI Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Update CI Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Update CI Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Update CI Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Update CI Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Update CI Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Update CI Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Update CI Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Update CI Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Update CI Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Update CI Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Update CI Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Fix typo Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Fix typo Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Modify CD Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Modify CD Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Modify CD Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Modify CD Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Update docs Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Format Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Fix Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Fix Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Address feedback Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> * Update doc Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> --------- Signed-off-by: James Xin <james.xin@improving.com> Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> Co-authored-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com> Co-authored-by: Alexey Temnikov <alexey.temnikov@improving.com>

Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com>

* Java: Compatibility layer module Signed-off-by: Prateek Kumar <prateek.kumar@improving.com> * Java: fix integration tests Signed-off-by: Prateek Kumar <prateek.kumar@improving.com> * Java: Fix codeql for java code Signed-off-by: Prateek Kumar <prateek.kumar@improving.com> * Java: Fix codeql java build Signed-off-by: Prateek Kumar <prateek.kumar@improving.com> * Java: Fix codeql java build Signed-off-by: Prateek Kumar <prateek.kumar@improving.com> * Java: Fix codeql java build Signed-off-by: Prateek Kumar <prateek.kumar@improving.com> * Java: Fix codeql java build Signed-off-by: Prateek Kumar <prateek.kumar@improving.com> * Java: Fix codeql java build Signed-off-by: Prateek Kumar <prateek.kumar@improving.com> * Java: Fix codeql java build Signed-off-by: Prateek Kumar <prateek.kumar@improving.com> * Java: Fix codeql java build Signed-off-by: Prateek Kumar <prateek.kumar@improving.com> * Java: Update java cd Signed-off-by: Prateek Kumar <prateek.kumar@improving.com> * Java: lint issues fixed Signed-off-by: Prateek Kumar <prateek.kumar@improving.com> * Java: Add signing configuration to jedis-compatibility build.gradle Signed-off-by: Prateek Kumar <prateek.kumar@improving.com> * Java: update dependency Signed-off-by: Prateek Kumar <prateek.kumar@improving.com> * Java: Update valkey-glide-jedis-compatibility file path Signed-off-by: Prateek Kumar <prateek.kumar@improving.com> * Java: Fix build.gradle publishing code Signed-off-by: Prateek Kumar <prateek.kumar@improving.com> --------- Signed-off-by: Prateek Kumar <prateek.kumar@improving.com>

- Add root AGENTS.md with unified context for mono-repo - Add Java AGENTS.md with Gradle, JNI, and platform classifier guidance - Add Node.js AGENTS.md with npm, TypeScript, and NAPI-RS context - Add Python AGENTS.md with async/sync clients and dev.py CLI - Add Go AGENTS.md with Make targets, CGO, and cross-compilation - Add Jedis compatibility AGENTS.md for drop-in replacement API Each file provides AI agents and developers with minimum but sufficient context including build commands, contribution requirements, quality gates, and language-specific development patterns. Closes #4738 Signed-off-by: jbrinkman <joe.brinkman@improving.com>

Co-authored-by: James Xin <james.xin@improving.com> Signed-off-by: Joseph Brinkman <joe.brinkman@improving.com>

jbrinkman requested a review from a team as a code owner September 16, 2025 12:59

jbrinkman requested a deployment to AWS_ACTIONS September 16, 2025 12:59 — with GitHub Actions Waiting

jbrinkman requested review from jamesx-improving, jduo, prateek-kumar-improving and yipin-chen September 16, 2025 13:00

yipin-chen approved these changes Sep 16, 2025

View reviewed changes

jduo reviewed Sep 16, 2025

View reviewed changes

AGENTS.md Show resolved Hide resolved

jamesx-improving approved these changes Sep 16, 2025

View reviewed changes

go/AGENTS.md Outdated Show resolved Hide resolved

go/AGENTS.md Show resolved Hide resolved

go/AGENTS.md Outdated Show resolved Hide resolved

prateek-kumar-improving approved these changes Sep 16, 2025

View reviewed changes

avifenesh reviewed Sep 17, 2025

View reviewed changes

node/AGENTS.md Show resolved Hide resolved

avifenesh reviewed Sep 17, 2025

View reviewed changes

node/AGENTS.md Show resolved Hide resolved

avifenesh reviewed Sep 17, 2025

View reviewed changes

node/AGENTS.md Show resolved Hide resolved

jbrinkman changed the base branch from release-2.1 to main September 18, 2025 17:06

jamesx-improving and others added 6 commits October 3, 2025 12:02

Revert go upload step change (#4716)

27f31ec

Signed-off-by: Alex Rehnby-Martin <alex.rehnby-martin@improving.com>

Fix client library reference

5656a18

Co-authored-by: James Xin <james.xin@improving.com> Signed-off-by: Joseph Brinkman <joe.brinkman@improving.com>

Update go/AGENTS.md

f448687

Co-authored-by: James Xin <james.xin@improving.com> Signed-off-by: Joseph Brinkman <joe.brinkman@improving.com>

jbrinkman force-pushed the jbrinkman/add-agents-md-files branch from d183641 to f448687 Compare October 3, 2025 16:04

jbrinkman requested a deployment to AWS_ACTIONS October 3, 2025 16:04 — with GitHub Actions Waiting

jbrinkman merged commit 7664ec0 into main Oct 3, 2025
60 of 64 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add AGENTS.md files for agentic tools across language bindings #4739

feat: add AGENTS.md files for agentic tools across language bindings #4739

Uh oh!

jbrinkman commented Sep 16, 2025

Uh oh!

yipin-chen left a comment

Uh oh!

Uh oh!

jamesx-improving left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

feat: add AGENTS.md files for agentic tools across language bindings #4739

feat: add AGENTS.md files for agentic tools across language bindings #4739

Uh oh!

Conversation

jbrinkman commented Sep 16, 2025

Summary

Changes

Root Repository

Language Bindings

Content Structure

Key Features

Benefits

Testing

Uh oh!

yipin-chen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jamesx-improving left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants