mirror of
https://github.com/agno-agi/agno.git
synced 2026-10-11 22:09:58 +00:00
chore: make AGENTS.md a symlink to CLAUDE.md (#9813)
## Summary AGENTS.md had drifted from CLAUDE.md (missing three Don't rules and the CI review section). Rather than re-sync by hand, this replaces AGENTS.md with a symlink to CLAUDE.md so the two can no longer diverge. - Removed the duplicated AGENTS.md content - Added `AGENTS.md -> CLAUDE.md` symlink; tools that read AGENTS.md follow it and see the full CLAUDE.md content ## Type of change - [x] Other: documentation / repo hygiene --- ## Checklist - [x] Code complies with style guidelines - [x] Ran format/validation scripts (`./scripts/format.sh` and `./scripts/validate.sh`) - N/A, no code changes - [x] Self-review completed - [x] Documentation updated (comments, docstrings) - [ ] Examples and guides: Relevant cookbook examples have been included or updated (if applicable) - [ ] Tested in clean environment - [ ] Tests added/updated (if applicable) ### Duplicate and AI-Generated PR Check - [x] I have searched existing [open pull requests](../../pulls) and confirmed that no other PR already addresses this issue - [ ] If a similar PR exists, I have explained below why this PR is a better approach - [x] Check if this PR was entirely AI-generated (by Copilot, Claude Code, Cursor, etc.) --- ## Additional Notes Windows checkouts without symlink support will see a one-line file containing `CLAUDE.md`; the repo tooling already assumes a Unix shell, so this is not a practical concern.
This commit is contained in:
Yash Pratap Solanky
@@ -1,241 +0,0 @@
|
||||
# AGENTS.md — Agno
|
||||
|
||||
Instructions for AI coding agents working on this codebase.
|
||||
|
||||
---
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
.
|
||||
├── libs/agno/agno/ # Core framework code
|
||||
├── cookbook/ # Examples, patterns and test cases (organized by topic)
|
||||
├── scripts/ # Development and build scripts
|
||||
├── specs/ # Design documents (symlinked, private)
|
||||
├── docs/ # Documentation (symlinked, private)
|
||||
└── .cursorrules # Coding patterns and conventions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Conductor Notes
|
||||
|
||||
When working in Conductor, you can use the `.context/` directory for scratch notes or agent-to-agent handoff artifacts. This directory is gitignored.
|
||||
|
||||
---
|
||||
|
||||
## Setting Up Symlinks
|
||||
|
||||
The `specs/` and `docs/` directories are symlinked from external locations. For a fresh clone or new workspace, create these symlinks:
|
||||
|
||||
```bash
|
||||
ln -s ~/code/specs specs
|
||||
ln -s ~/code/docs docs
|
||||
```
|
||||
|
||||
These contain private design documents and documentation that are not checked into the repository.
|
||||
|
||||
---
|
||||
|
||||
## Virtual Environments
|
||||
|
||||
This project uses two virtual environments:
|
||||
|
||||
| Environment | Purpose | Setup |
|
||||
|-------------|---------|-------|
|
||||
| `.venv/` | Development: tests, formatting, validation | `./scripts/dev_setup.sh` |
|
||||
| `.venvs/demo/` | Cookbooks: has all demo dependencies | `./scripts/demo_setup.sh` |
|
||||
|
||||
**Use `.venv`** for development tasks (`pytest`, `./scripts/format.sh`, `./scripts/validate.sh`).
|
||||
|
||||
**Use `.venvs/demo`** for running cookbook examples.
|
||||
|
||||
---
|
||||
|
||||
## Testing Cookbooks
|
||||
|
||||
Apart from implementing features, your most important task will be to test and maintain the cookbooks in `cookbook/` directory.
|
||||
|
||||
> See `cookbook/08_learning/` for the golden standard.
|
||||
|
||||
### Quick Reference
|
||||
|
||||
**Test Environment:**
|
||||
|
||||
```bash
|
||||
# Virtual environment with all dependencies
|
||||
.venvs/demo/bin/python
|
||||
|
||||
# Setup (if needed)
|
||||
./scripts/demo_setup.sh
|
||||
|
||||
# Database (if needed)
|
||||
./cookbook/scripts/run_pgvector.sh
|
||||
```
|
||||
|
||||
**Run a cookbook:**
|
||||
```bash
|
||||
.venvs/demo/bin/python cookbook/<folder>/<file>.py
|
||||
```
|
||||
|
||||
### Expected Cookbook Structure
|
||||
|
||||
Each cookbook folder should have the following files:
|
||||
- `README.md` — The README for the cookbook.
|
||||
- `TEST_LOG.md` — Test results log.
|
||||
|
||||
### Testing Workflow
|
||||
|
||||
**1. Before Testing**
|
||||
- Ensure the virtual environment exists (run `./scripts/demo_setup.sh` if needed)
|
||||
- Start any required services (e.g., `./cookbook/scripts/run_pgvector.sh`)
|
||||
|
||||
**2. Running Tests**
|
||||
```bash
|
||||
# Run individual cookbook
|
||||
.venvs/demo/bin/python cookbook/<folder>/<file>.py
|
||||
|
||||
# Tail output for long tests
|
||||
.venvs/demo/bin/python cookbook/<folder>/<file>.py 2>&1 | tail -100
|
||||
```
|
||||
|
||||
**3. Updating TEST_LOG.md**
|
||||
|
||||
After each test, update the cookbook's `TEST_LOG.md` with:
|
||||
- Test name and path
|
||||
- Status: PASS or FAIL
|
||||
- Brief description of what was tested
|
||||
- Any notable observations or issues
|
||||
|
||||
Format:
|
||||
```markdown
|
||||
### filename.py
|
||||
|
||||
**Status:** PASS/FAIL
|
||||
|
||||
**Description:** What the test does and what was observed.
|
||||
|
||||
**Result:** Summary of success/failure.
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Code Locations
|
||||
|
||||
| What | Where |
|
||||
|------|-------|
|
||||
| Core agent code | `libs/agno/agno/agent/` |
|
||||
| Teams | `libs/agno/agno/team/` |
|
||||
| Workflows | `libs/agno/agno/workflow/` |
|
||||
| Tools | `libs/agno/agno/tools/` |
|
||||
| Models | `libs/agno/agno/models/` |
|
||||
| Knowledge/RAG | `libs/agno/agno/knowledge/` |
|
||||
| Memory | `libs/agno/agno/memory/` |
|
||||
| Learning | `libs/agno/agno/learn/` |
|
||||
| Database adapters | `libs/agno/agno/db/` |
|
||||
| Vector databases | `libs/agno/agno/vectordb/` |
|
||||
| Tests | `libs/agno/tests/` |
|
||||
|
||||
---
|
||||
|
||||
## Coding Patterns
|
||||
|
||||
See `.cursorrules` for detailed patterns. Key rules:
|
||||
|
||||
- **Never create agents in loops** — reuse them for performance
|
||||
- **Use output_schema** for structured responses
|
||||
- **PostgreSQL in production**, SQLite for dev only
|
||||
- **Start with single agent**, scale up only when needed
|
||||
- **Both sync and async** — all public methods need both variants
|
||||
|
||||
---
|
||||
|
||||
## Running Code
|
||||
|
||||
**Running cookbooks:**
|
||||
```bash
|
||||
.venvs/demo/bin/python cookbook/<folder>/<file>.py
|
||||
```
|
||||
|
||||
**Running tests:**
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
pytest libs/agno/tests/
|
||||
|
||||
# Run a specific test file
|
||||
pytest libs/agno/tests/unit/test_agent.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When Implementing Features
|
||||
|
||||
1. **Check for design doc** in `specs/` — if it exists, follow it
|
||||
2. **Look at existing patterns** — find similar code and follow conventions
|
||||
3. **Create a cookbook** — every pattern should have an example
|
||||
4. **Update implementation.md** — mark what's done
|
||||
|
||||
---
|
||||
|
||||
## Before Submitting Code
|
||||
|
||||
**Always run these scripts before pushing code or creating a PR:**
|
||||
|
||||
```bash
|
||||
# Activate the virtual environment first
|
||||
source .venv/bin/activate
|
||||
|
||||
# Format all code (ruff format)
|
||||
./scripts/format.sh
|
||||
|
||||
# Validate all code (ruff check, mypy)
|
||||
./scripts/validate.sh
|
||||
```
|
||||
|
||||
Both scripts must pass with no errors before code review.
|
||||
|
||||
**PR Title Format:**
|
||||
|
||||
PR titles must follow one of these formats:
|
||||
- `type: description` — e.g., `feat: add workflow serialization`
|
||||
- `[type] description` — e.g., `[feat] add workflow serialization`
|
||||
- `type-kebab-case` — e.g., `feat-workflow-serialization`
|
||||
|
||||
Valid types: `feat`, `fix`, `cookbook`, `test`, `refactor`, `chore`, `style`, `revert`, `release`
|
||||
|
||||
**PR Description:**
|
||||
|
||||
Always follow the PR template in `.github/pull_request_template.md`. Include:
|
||||
- Summary of changes
|
||||
- Type of change (bug fix, new feature, etc.)
|
||||
- Completed checklist items
|
||||
- Any additional context
|
||||
|
||||
---
|
||||
|
||||
## GitHub Operations
|
||||
|
||||
**Updating PR descriptions:**
|
||||
|
||||
The `gh pr edit` command may fail with GraphQL errors related to classic projects. Use the API directly instead:
|
||||
|
||||
```bash
|
||||
# Update PR body
|
||||
gh api repos/agno-agi/agno/pulls/<PR_NUMBER> -X PATCH -f body="<PR_BODY>"
|
||||
|
||||
# Or with a file
|
||||
gh api repos/agno-agi/agno/pulls/<PR_NUMBER> -X PATCH -f body="$(cat /path/to/body.md)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Don't
|
||||
|
||||
- Don't implement features without checking for a design doc first
|
||||
- Don't use f-strings for print lines where there are no variables
|
||||
- Don't use emojis in examples and print lines
|
||||
- Don't skip async variants of public methods
|
||||
- Don't push code without running `./scripts/format.sh` and `./scripts/validate.sh`
|
||||
- Don't submit a PR without a detailed PR description. Always follow the PR template provided in `.github/pull_request_template.md`.
|
||||
@@ -1,6 +1,6 @@
|
||||
# CLAUDE.md — Agno
|
||||
# Agno - Agent Instructions
|
||||
|
||||
Instructions for Claude Code when working on this codebase.
|
||||
Instructions for AI coding agents (Claude Code, Codex, Cursor, etc.) working on this codebase.
|
||||
|
||||
---
|
||||
|
||||
@@ -254,5 +254,5 @@ When running in GitHub Actions (CI), always end your response with a plain-text
|
||||
Agno-specific checks to always verify:
|
||||
- Both sync and async variants exist for all new public methods
|
||||
- No agent creation inside loops (agents should be reused)
|
||||
- CLAUDE.md coding patterns are followed
|
||||
- Coding patterns in this file are followed
|
||||
- No f-strings for print lines where there are no variables
|
||||
|
||||
Reference in New Issue
Block a user