Add AGENTS.md for AI agent guidance

[ralphbean]

User description

Summary

• Add AGENTS.md containing project-specific guidance for AI coding agents
• Symlink CLAUDE.md to AGENTS.md for compatibility with Claude Code
• Add .agentready to .gitignore

Details

The AGENTS.md file provides:

• Quick reference commands for testing (tox), linting (flake8, black, isort), and running the service
• High-level architecture overview explaining the data flow and core components
• Links to existing documentation (README.md, CONTRIBUTING.md) to avoid duplication

This helps AI agents quickly understand the codebase structure and common development tasks.

🤖 Generated with Claude Code

---

PR Type

Documentation

---

Description

• Add AGENTS.md with AI agent guidance and architecture overview

• Create CLAUDE.md symlink for Claude Code compatibility

• Add .agentready to .gitignore for agent-related files

---

Diagram Walkthrough

flowchart LR
  A["AGENTS.md<br/>AI Agent Guidance"] --> B["Quick Reference<br/>Commands"]
  A --> C["Architecture<br/>Overview"]
  A --> D["Component<br/>Documentation"]
  E["CLAUDE.md<br/>Symlink"] -.->|"points to"| A
  B --> F["Testing/Linting<br/>Commands"]
  C --> G["Data Flow<br/>Diagram"]
  D --> H["Core Components<br/>Description"]

Loading

File Walkthrough

	Relevant files
Documentation	AGENTS.md AI agent guidance with commands and architecture                  AGENTS.md Provides comprehensive guidance for AI coding agents working with the codebase Includes quick reference commands for testing with tox, linting with flake8/black/isort Documents the architecture with data flow and core component descriptions References existing documentation (README.md, CONTRIBUTING.md) to avoid duplication +102/-0  CLAUDE.md Symlink to AGENTS.md for Claude Code                                          CLAUDE.md Creates a symlink pointing to AGENTS.md for Claude Code compatibility Enables Claude Code to automatically discover agent guidance +1/-0
Configuration changes	.gitignore Add .agentready to gitignore                                                          .gitignore Adds .agentready to gitignore to exclude agent-related temporary files

---

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[ralphbean]

I'm using our repo here as a test for https://github.com/ambient-code/agentready

[qodo-code-review]

PR Code Suggestions ✨

Latest suggestions up to 817e896

Category	Suggestion	Impact
General	✅ Fix incorrect configuration requirement Suggestion Impact: Updated the AGENTS.md configuration description to eliminate the duplicate key and clarify that `issue_updates` must include `github_project_fields`, additionally noting `github_project_number` is optional. code diff: @@ -100,7 +99,7 @@ - **Purpose**: Enriches JIRA issues with custom field data from GitHub Projects that isn't available in standard GitHub issue events - **GraphQL API**: Uses GitHub's GraphQL API to fetch project field values (upstream_issue.py:32-111) - **Supported fields**: priority (mapped to JIRA priority) and storypoints (mapped to JIRA story points) -- **Configuration**: Requires `github_project_number`, `github_project_fields`, and `github_project_fields` in `issue_updates` +- **Configuration**: Requires the `github_project_fields` configuration key and the `"github_project_fields"` entry in the `issue_updates` key. The `github_project_number` key is optional (needed only for disambiguation when issues belong to multiple projects) - **Field mapping**: Supports custom mappings (e.g., GitHub "P0" → JIRA "Blocker") Correct the description of required configuration keys for GitHub Projects integration to remove a repeated key and clarify the usage of issue_updates. AGENTS.md [103] -- **Configuration**: Requires `github_project_number`, `github_project_fields`, and `github_project_fields` in `issue_updates` +- **Configuration**: Requires `github_project_number` and `github_project_fields`, and `issue_updates` must include `github_project_fields` [Suggestion processed] Suggestion importance[1-10]: 5 __ Why: The suggestion correctly identifies a repetitive and confusing statement in the documentation and proposes a clearer, more accurate version that aligns with the provided example.	Low
	✅ Correct a spelling mistake Suggestion Impact: The line containing the misspelling ("spectactular") was removed from the document, eliminating the typo, but it was not corrected in-place as suggested. code diff: -- Manages upstream rate limiting (and does a less than spectactular job at it) Correct the spelling of "spectactular" to "spectacular". AGENTS.md [84] -- Manages upstream rate limiting (and does a less than spectactular job at it) +- Manages upstream rate limiting (and does a less than spectacular job at it) [Suggestion processed] Suggestion importance[1-10]: 2 __ Why: The suggestion correctly identifies and fixes a spelling error, which is a minor but valid improvement to the documentation's quality.	Low
Update

---

Previous suggestions

Suggestions up to commit d242b79

Category	Suggestion	Impact
General	Replace duplicate with reference To avoid maintenance overhead, replace the duplicated content in CLAUDE.md with a reference to AGENTS.md. CLAUDE.md [1-102] # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. -... +See [AGENTS.md](AGENTS.md) for up-to-date AI agent guidance. Suggestion importance[1-10]: 7 __ Why: This is an excellent suggestion that significantly improves maintainability by eliminating duplicated content between AGENTS.md and CLAUDE.md, establishing a single source of truth.	Medium
	Correct document header Correct the header in AGENTS.md to match its filename for clarity and consistency. AGENTS.md [1] -# CLAUDE.md +# AGENTS.md Suggestion importance[1-10]: 4 __ Why: This is a valid and good suggestion. The file AGENTS.md has a title # CLAUDE.md, which is inconsistent with the filename and its purpose as a general guide.	Low

[ralphbean]

Ah, the duplicate things that qodo sees here are red herrings, b/c CLAUDE.md is a symlink to AGENTS.md. There's not really duplication there.

[webbnh]

Looks good. I just have a couple of additional comments.

[webbnh]

@qodo-code-review, I don't know if you read these comments, but the duplication between AGENTS.md and CLAUDE.md is because the CLAUDE.md file is a symbolic link to AGENTS.md, so the contents appear to be the same, depending on how they are viewed.

[webbnh]

👍