4.6 KiB
Task: Expand AGENTS.md for Enterprise AI Development Standards
Your role is Principal Software Architect, Staff Engineer, Enterprise UI/UX Architect, and AI Workflow Designer.
Objective
Review the existing AGENTS.md and evolve it into a more complete AI engineering guide.
This is an expansion task, NOT a rewrite.
The existing document already contains valuable project rules. Preserve them and extend them where appropriate.
Primary Goal
Improve AI collaboration quality without changing the project's architecture or development philosophy.
The updated AGENTS.md should better support AI coding agents such as Codex, Claude Code, Gemini CLI, Cursor, Windsurf, and future coding assistants.
Requirements
1. Preserve Existing Rules
Do NOT remove existing sections unless they are clearly obsolete.
Keep existing:
- Architecture rules
- Foundation reuse
- Governance
- Historical review
- Authentication
- React Query
- CRUD rules
- Date formatting
- Route Handler patterns
- Project structure
- Coding conventions
Improve wording only if necessary.
2. Add Missing Enterprise Sections
Expand AGENTS.md with new sections where appropriate.
Possible additions include:
AI Workflow
Define the expected workflow before implementation.
Example:
- Requirement Analysis
- Historical Review
- Architecture Review
- Existing Pattern Discovery
- Implementation Plan
- Implementation
- Self Review
- Validation
- Delivery
Existing Pattern Discovery
Before creating any new:
- Component
- Hook
- Utility
- Dialog
- Service
- API
- Layout
- Table
- Form
- Provider
AI MUST search the project for an existing implementation.
Reuse before creating.
AI Skill Composition
Define responsibilities for external AI skills.
Example:
Project Standards ↓ Architecture ↓ Existing Code Pattern ↓ External Skill ↓ UI Polish
Separate responsibilities such as:
- Code architecture
- Code pattern
- UI/UX
- Accessibility
- Performance
- Documentation
Project rules always have highest priority.
UI/UX Quality Standards
Add enterprise UI expectations.
Examples:
- visual hierarchy
- spacing consistency
- typography hierarchy
- responsive layouts
- dark mode
- loading state
- empty state
- error state
- skeleton loading
- accessibility
- keyboard navigation
- consistent action placement
Design Review Checklist
Require AI to verify:
- readability
- consistency
- spacing
- responsiveness
- accessibility
- component reuse
- visual balance
- unnecessary complexity
- enterprise appearance
before considering a task complete.
Refactoring Policy
Encourage:
- improve existing code
- extend existing modules
- minimize breaking changes
Avoid:
- unnecessary rewrites
- duplicate implementations
- introducing new patterns without justification
Component Reuse Policy
Before creating:
- Card
- Table
- Dialog
- Form
- Toolbar
- Action Bar
- Preview Panel
- Status Badge
AI must search for reusable components first.
Enterprise Dashboard Standards
When implementing dashboard pages:
Prefer:
- clear information hierarchy
- balanced layouts
- action grouping
- summary cards
- sticky action panels when appropriate
- proper whitespace
- predictable navigation
Avoid visual clutter.
Self Review Section
Before considering implementation complete, AI must verify:
✓ Architecture follows project standards
✓ Existing foundations reused
✓ Existing APIs reused
✓ Existing components reused
✓ No duplicated business logic
✓ UI consistency maintained
✓ Accessibility considered
✓ Responsive layout verified
✓ Loading/Error/Empty states implemented
✓ Code remains maintainable
Future Compatibility
The AGENTS.md should remain AI-agnostic.
Do not reference only one AI tool.
The guidance should work equally well with:
- Codex
- Claude Code
- Cursor
- Gemini CLI
- Windsurf
- Cline
- future coding agents
Constraints
- Do NOT change business rules.
- Do NOT change architecture.
- Do NOT replace existing standards.
- Expand rather than rewrite.
- Preserve backward compatibility.
Expected Deliverables
- Review summary
Explain:
- what already exists
- what is missing
- why each new section is valuable
- Updated AGENTS.md
Integrate new sections into appropriate locations.
Avoid duplication.
Maintain a consistent writing style.
- Change Summary
Categorize changes into:
- Added
- Expanded
- Clarified
- Deprecated (if any)
- Quality Review
Verify the final AGENTS.md is:
- internally consistent
- free of conflicting rules
- suitable for long-term maintenance
- optimized for AI-assisted enterprise software development