AGENTS.md@.architecture/templates · git:20251120.16709b5 · 2025-11-20 · sha256 d00e58dd9518c57a
AGENTS.md@.architecture/templates git:20251120.16709b5A
Immutable. This exact content is served forever at /api/v1/blob/d00e58dd9518c57a.
# AGENTS.md - AI Software Architect Framework > **For [AI Assistant] Users**: This file contains cross-platform instructions for the AI Software Architect framework. For assistant-specific features, see the references at the end of this file. ## Project Overview [PROJECT_NAME] uses the AI Software Architect framework to implement rigorous software architecture practices with AI assistant collaboration. The framework provides structured architecture documentation, multi-perspective reviews, and architectural decision tracking. ## Framework Setup The AI Software Architect framework is installed in the `.architecture/` directory and provides: - **Architecture Documentation**: Centralized repository of architectural decisions and reviews - **Multi-Perspective Reviews**: Specialized reviewers from different architectural domains - **Decision Records (ADRs)**: Structured documentation of architectural decisions - **Recalibration Process**: Translating architectural reviews into implementation plans - **Pragmatic Mode**: Optional YAGNI enforcement to prevent over-engineering ### Directory Structure ``` .architecture/ ├── members.yml # Architecture review team members ├── principles.md # Core architectural principles ├── config.yml # Framework configuration (including pragmatic mode) ├── decisions/ # Architectural Decision Records (ADRs) │ └── adrs/ # Numbered ADR documents ├── reviews/ # Architecture review documents ├── recalibration/ # Implementation planning documents └── templates/ # Templates for ADRs, reviews, etc. ``` ## Core Workflows ### Requesting Architecture Reviews Architecture reviews provide multi-perspective analysis of architectural decisions. Use phrases like: - "Start architecture review for version X.Y.Z" - "Start architecture review for [feature name]" - "Review architecture for [component description]" The review process includes: 1. **Individual Review Phase**: Each architecture member reviews independently 2. **Collaborative Discussion Phase**: Members discuss findings and trade-offs 3. **Final Report Phase**: Consolidated recommendations and action items Review documents are created in `.architecture/reviews/` using version numbers (e.g., `1-0-0.md`) or feature names (e.g., `feature-name.md`). ### Requesting Specialist Reviews For focused architectural feedback from a specific specialist, use phrases like: - "Ask [Specialist Role] to review [target]" - "Get [Specialist]'s opinion on [topic]" - "Have [Role] review these changes" Example: "Ask Security Specialist to review authentication implementation" Available specialists are defined in `.architecture/members.yml`. Common roles include: - Systems Architect (overall system coherence) - Domain Expert (business logic representation) - Security Specialist (security implications) - Performance Specialist (performance optimization) - Maintainability Expert (code quality and technical debt) - AI Engineer (AI/ML integration patterns) - Pragmatic Enforcer (YAGNI and simplicity advocacy) Specialist review documents are created in `.architecture/reviews/` with format: `[role]-[topic].md`. ### Creating Architectural Decision Records (ADRs) ADRs document significant architectural decisions. To create an ADR: 1. Use phrases like: "Create ADR for [topic]" or "Document architectural decision for [topic]" 2. Provide context about the decision being made 3. Include alternatives considered 4. Document consequences (positive, negative, neutral) ADRs are stored in `.architecture/decisions/adrs/` with sequential numbering: `ADR-001-topic.md`, `ADR-002-topic.md`, etc. ADR template is available at `.architecture/templates/adr-template.md`. ### Enabling Pragmatic Mode Pragmatic mode adds YAGNI enforcement to prevent over-engineering. Enable it with phrases like: - "Enable pragmatic mode" - "Turn on YAGNI enforcement" - "Activate simplicity guard" - "Challenge complexity" Configuration is stored in `.architecture/config.yml`. Three intensity modes: - **Strict**: Aggressive challenges, require strong justification, default to defer/simplify - **Balanced**: Thoughtful challenges, accept justified complexity, seek middle ground - **Lenient**: Raise concerns without blocking, suggest alternatives as options When enabled, the Pragmatic Enforcer member participates in reviews and ADR creation, challenging: - Unnecessary abstractions - Premature optimization - Speculative features - Over-engineered solutions Pragmatic analysis includes: - **Necessity Assessment** (0-10): Current need, future need, cost of waiting - **Complexity Assessment** (0-10): Added complexity, maintenance burden, learning curve - **Simpler Alternatives**: Concrete proposals for simpler approaches - **Recommendations**: Implement now / Simplified version / Defer / Skip Deferred decisions are tracked in `.architecture/deferrals.md` with trigger conditions for future implementation. ### Architectural Recalibration After architecture reviews, conduct recalibration to translate findings into action: - "Start architecture recalibration for version X.Y.Z" - "Recalibrate architecture for [feature name]" Recalibration includes: 1. **Review Analysis & Prioritization**: Categorize and prioritize recommendations 2. **Architectural Plan Update**: Update ADRs and documentation 3. **Documentation Refresh**: Ensure docs reflect new direction 4. **Implementation Roadmapping**: Create detailed implementation plans 5. **Progress Tracking**: Monitor implementation progress Recalibration documents are stored in `.architecture/recalibration/` using version numbers or feature names. ## Architecture Principles This project follows architectural principles defined in `.architecture/principles.md`. Key principles include: - **Livable Code**: Design for developers who inhabit the codebase - **Clarity over Cleverness**: Prefer simple, clear designs - **Separation of Concerns**: Clear boundaries and single responsibilities - **Evolvability**: Facilitate change without complete rewrites - **Observability**: System provides insights into behavior and state - **Security by Design**: Security integral to architecture, not afterthought - **Domain-Centric Design**: Reflect and serve the problem domain - **Pragmatic Simplicity**: Value working solutions over theoretical perfection For detailed explanations and application guidelines, see `.architecture/principles.md`. ## Build & Test (Framework Development) If working on the AI Software Architect framework itself: ### Testing Framework Components ```bash # Verify directory structure ls -la .architecture/ # Check configuration cat .architecture/config.yml # List architecture members cat .architecture/members.yml # View templates ls .architecture/templates/ ``` ### Validating ADRs and Reviews - ADRs should follow template at `.architecture/templates/adr-template.md` - Reviews should follow template at `.architecture/templates/review-template.md` - Recalibration should follow template at `.architecture/templates/recalibration_plan.md` ## Project-Specific Information [PROJECT_TECH_STACK] [PROJECT_BUILD_COMMANDS] [PROJECT_TEST_COMMANDS] [PROJECT_CONVENTIONS] ## Assistant-Specific Features The AI Software Architect framework provides enhanced capabilities for specific AI coding assistants: ### Claude Code Claude Code users have access to enhanced features including: - **Claude Skills**: Reusable skills for setup, reviews, ADR creation, and status checks - **MCP Server Integration**: Tools for architecture operations via Model Context Protocol - **Slash Commands**: Custom commands for framework operations - **Enhanced Setup**: Intelligent project analysis and template customization **See [CLAUDE.md](../CLAUDE.md) for complete Claude Code documentation.** ### Cursor Cursor users can configure the framework via: - **Configuration**: See `.coding-assistants/cursor/README.md` - **Rules**: Custom rules for architecture operations - **Integration**: Tab completion and inline suggestions **See [.coding-assistants/cursor/README.md](../.coding-assistants/cursor/README.md) for details.** ### GitHub Copilot / Codex Copilot users can access framework features via: - **Configuration**: See `.coding-assistants/codex/README.md` - **Comments**: Use comments to trigger architecture operations - **Integration**: Inline suggestions for ADRs and reviews **See [.coding-assistants/codex/README.md](../.coding-assistants/codex/README.md) for details.** ### Other AI Assistants The framework works with any AI assistant that can read markdown files and follow structured instructions. Key entry points: - **This file (AGENTS.md)**: Cross-platform instructions - **.architecture/**: All framework artifacts and templates - **principles.md**: Architectural principles to apply - **members.yml**: Available architecture reviewers - **templates/**: Templates for ADRs, reviews, and recalibration ## Additional Resources - **Framework Principles**: `.architecture/principles.md` - **Architecture Members**: `.architecture/members.yml` - **Configuration**: `.architecture/config.yml` - **ADR Template**: `.architecture/templates/adr-template.md` - **Review Template**: `.architecture/templates/review-template.md` - **Recalibration Template**: `.architecture/templates/recalibration_plan.md` - **Example ADRs**: `.architecture/decisions/adrs/` - **Example Reviews**: `.architecture/reviews/` --- **Framework Version**: [FRAMEWORK_VERSION] **Last Updated**: [LAST_UPDATED] **Maintained By**: AI Software Architect Framework