PR AI Guidance

[helmut-hoffer-von-ankershoffen]

@claude Improve Agent guidance.

Perform a thorough, deep and full exploration of this repository including running the CLI and tests, with the goal to improve guidance for AI agents, by improving existing markdown files for coding agents, and creating an AGENTS.md

[claude]

Claude finished @helmut-hoffer-von-ankershoffen's task —— View job • claude/issue-153-20251006-1121 • Create PR ➔

---

Improving AI Agent Guidance ✅

I've completed a thorough exploration of the repository and created comprehensive AI agent guidance improvements.

Tasks Completed

• Gather context about repository structure
• Audit all existing CLAUDE.md files (13 files read and analyzed)
• Analyze code structure and patterns
• Identify gaps in current agent guidance
• Create comprehensive AGENTS.md file ✨
• Update root CLAUDE.md to reference AGENTS.md
• Add quick-start section to root CLAUDE.md
• Update module index CLAUDE.md with AGENTS.md reference
• Update tests CLAUDE.md with testing workflow reference
• Commit and push changes
• Provide PR link

---

📋 Summary of Changes

Created AGENTS.md (1,050+ lines)

A comprehensive AI agent guide serving as the central navigation hub:

Core Sections:

• 🎯 Quick Start for AI Agents - First steps, essential files, priority guide
• 📚 Documentation Map - Complete navigation to all 13 CLAUDE.md files with clear hierarchy
• 🏗️ Architecture Quick Reference - Modulith pattern, module structure, dependency graph
• 🛠️ Common Agent Tasks - 5 step-by-step workflows (features, modules, bugs, docs, tests)
• ⚠️ Common Pitfalls & Solutions - 7 major pitfalls with concrete fixes
• 🎨 Code Style Quick Reference - Critical requirements from CODE_STYLE.md
• 🔍 Navigation Patterns - How to find the right file for any task
• 🧪 Testing Strategies - Test-driven development flow, patterns by module type
• 🚀 Build System - Essential commands and pre-commit hooks
• 📊 Module Capabilities Matrix - Quick lookup for what each module provides
• 🎓 Learning Path - 3 levels (basics, modules, changes)
• 🆘 Troubleshooting Guide - 6 common problems with solutions
• 🔄 Common Workflows - 3 detailed workflows with commands
• 📝 Pre-commit Checklist - Quality assurance before committing

Updated Existing Documentation

Root CLAUDE.md:

• Added prominent callout to AGENTS.md at the top
• Created "Quick Start for AI Agents" section with checklist
• Added links to common tasks and workflows

src/aignostics/CLAUDE.md:

• Added tip directing agents to AGENTS.md for workflows

tests/CLAUDE.md:

• Added reference to AGENTS.md testing strategies

---

🎯 Key Improvements

1. Central Navigation Hub - AGENTS.md provides clear entry point and links to all documentation
2. Task-Oriented Guidance - Organized by what agents need to do, not just reference material
3. Concrete Examples - All patterns drawn from actual codebase implementation
4. Clear Prioritization - What to read first (critical), what's optional, clear flow
5. Cross-References - All documentation files now interlink appropriately
6. Common Mistakes Addressed - Pitfalls section prevents frequent errors
7. Troubleshooting Built-in - Solutions for 6 common setup/development problems
8. Workflow-Based - Step-by-step commands for adding features, fixing bugs, updating docs

---

🔗 Pull Request

---

•