Skip to content

docs: add tool-agnostic AGENTS.md for AI coding agents#1469

Open
jsonmp-k8 wants to merge 3 commits intokagent-dev:mainfrom
jsonmp-k8:add-agents-md
Open

docs: add tool-agnostic AGENTS.md for AI coding agents#1469
jsonmp-k8 wants to merge 3 commits intokagent-dev:mainfrom
jsonmp-k8:add-agents-md

Conversation

@jsonmp-k8
Copy link
Contributor

@jsonmp-k8 jsonmp-k8 commented Mar 10, 2026 •
edited
Loading

Summary

  • Adds a tool-agnostic AGENTS.md that works across all AI coding agents (Claude Code, Cursor, Copilot, etc.)
  • Adds a CLAUDE.md pointer file so Claude Code automatically loads AGENTS.md instructions
  • Includes sections on code reuse (avoid duplicating functions/utilities) and naming conventions (use descriptive variable and function names)
  • Adds expanded coverage of CI/CD pipeline, architectural patterns (MCP, memory system, HTTP client SDK), and per-language development details

Changes

  • Added: AGENTS.md with the following sections:
    • Code Reuse — guidelines to search for existing utilities before writing new code, consolidate duplicated logic
    • Naming Conventions — descriptive names required across Go, Python, and TypeScript; no abbreviations
    • CI/CD Pipeline — detailed breakdown of all CI stages and additional workflows
    • Key Architectural Patterns — MCP integration, memory system, HTTP client SDK
    • Python Development — UV, Ruff, Pytest details
    • UI Development — framework and tooling details
  • Added: CLAUDE.md that references AGENTS.md, ensuring Claude Code automatically picks up the instructions

Test plan

  • Verify AGENTS.md renders correctly on GitHub
  • Verify CLAUDE.md causes Claude Code to load AGENTS.md instructions

Copilot AI review requested due to automatic review settings March 10, 2026 02:41
Copilot AI reviewed Mar 10, 2026
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Replaces the repository’s AI-agent guidance by removing CLAUDE.md and introducing a new consolidated AGENTS.md guide for agents working in the kagent repo.

Changes:

  • Delete the existing CLAUDE.md development guide.
  • Add AGENTS.md with expanded project architecture, repo layout, build/test commands, and conventions.
  • Document CI/CD pipeline expectations and key architectural patterns (MCP, memory, SDK, etc.).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File Description
CLAUDE.md Removes the previous AI-agent development guide.
AGENTS.md Adds a new, expanded AI-agent repository guide (commands, conventions, architecture, CI overview).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@EItanya
Copy link
Contributor

EItanya commented Mar 10, 2026

Can you please structure the diff such that it’s more apparent what changed? Maybe moving the file and then editing

@jsonmp-k8
Copy link
Contributor Author

jsonmp-k8 commented Mar 10, 2026 •
edited
Loading

Can you please structure the diff such that it’s more apparent what changed? Maybe moving the file and then editing

Added the rename and changes into two different commits. Other than formatting, My changes were this https://github.com/kagent-dev/kagent/pull/1469/changes#diff-a54ff182c7e8acf56acfd6e4b9c3ff41e2c41a31c9b211b2deb9df75d9a478f9R239-R254

@jsonmp-k8
Copy link
Contributor Author

jsonmp-k8 commented Mar 11, 2026

Can you please structure the diff such that it’s more apparent what changed? Maybe moving the file and then editing

Added the rename and changes into two different commits. Other than formatting, My changes were this https://github.com/kagent-dev/kagent/pull/1469/changes#diff-a54ff182c7e8acf56acfd6e4b9c3ff41e2c41a31c9b211b2deb9df75d9a478f9R239-R254
@EItanya please let me know if you are good with this?

@EItanya
Copy link
Contributor

EItanya commented Mar 11, 2026

Iirc Claude doesn’t pick up agents.md, has that been fixed? If not I think we might need a solution that works for Claude code

@jsonmp-k8
Copy link
Contributor Author

jsonmp-k8 commented Mar 11, 2026

Iirc Claude doesn’t pick up agents.md, has that been fixed? If not I think we might need a solution that works for Claude code

Added a link to the claude.md file to be on the safer side and Agents.md file can be the default file referred by all AI tools

@jsonmp-k8 jsonmp-k8 changed the title docs: replace CLAUDE.md with tool-agnostic AGENTS.md docs: add tool-agnostic AGENTS.md for AI coding agents Mar 11, 2026
@jsonmp-k8
docs: rename CLAUDE.md to AGENTS.md
d62f94c 
Rename to a tool-agnostic filename that works across all AI coding
agents, not just Claude Code.

Signed-off-by: Jaison Paul <paul.jaison@gmail.com>
@jsonmp-k8
docs: expand AGENTS.md with code reuse, naming, and architecture sect…
97e8815 
…ions

- Add code reuse section to discourage duplicating functions/utilities
- Add naming conventions section requiring descriptive variable and
  function names across all languages
- Expand repo structure with docker, contrib, design, docs, scripts, test
- Add per-language development details (Go modules, Python tooling, UI stack)
- Add CI/CD pipeline breakdown and architectural patterns (MCP, memory, SDK)
- Fix make lint description to clarify it only covers Go + Python
- Add separate UI lint command (npm -C ui run lint)

Signed-off-by: Jaison Paul <paul.jaison@gmail.com>
@jsonmp-k8
docs: add CLAUDE.md referencing AGENTS.md
2dcb526 
Ensures Claude Code automatically loads AGENTS.md instructions
by adding a CLAUDE.md pointer file.

Signed-off-by: Jaison Paul <paul.jaison@gmail.com>
@EItanya
Copy link
Contributor

EItanya commented Mar 11, 2026

https://www.reddit.com/r/ClaudeCode/comments/1rlc8zi/agentsmd_standard/

@jsonmp-k8
Copy link
Contributor Author

jsonmp-k8 commented Mar 11, 2026 •
edited
Loading

https://www.reddit.com/r/ClaudeCode/comments/1rlc8zi/agentsmd_standard/

Thank you, so the latest change should help

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@EItanya EItanya Awaiting requested review from EItanya EItanya is a code owner

@peterj peterj Awaiting requested review from peterj peterj is a code owner

@ilackarms ilackarms Awaiting requested review from ilackarms ilackarms is a code owner

@yuval-k yuval-k Awaiting requested review from yuval-k yuval-k is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@jsonmp-k8 @EItanya