aiready-best-practices
Scannednpx machina-cli add skill caopengau/aiready-skills/aiready-best-practices --openclawAIReady Best Practices
Guidelines for writing AI-friendly codebases that AI coding assistants can understand and maintain effectively. Based on analysis of thousands of repositories and common AI model failure patterns. Covers pattern detection, AI signal clarity, context optimization, change amplification, agent grounding, consistency checking, documentation, testability, and dependency management.
Core Capabilities
- AI Signal Clarity: Principles for reducing ambiguity in code.
- Context Optimization: Strategies for minimizing context window waste.
- Pattern Detection: Identifying and consolidating semantic duplicates.
- Consistency: Maintaining uniform naming and architectural patterns.
- Health Assessment: Using
aiready scanfor proactive codebase auditing.
Usage for Agents
Full instructions are available in AGENTS.md.
[!NOTE] AGENTS.md is automatically generated from individual rules in the
rules/directory. Contributors should modify the source rules rather than the compiled file.
Quick Commands (via npx)
- Measure Health:
npx @aiready/cli scan . - Check Consistency:
npx @aiready/cli consistency . - Detect Duplicates:
npx @aiready/cli patterns .
Source
git clone https://github.com/caopengau/aiready-skills/blob/main/aiready-best-practices/SKILL.mdView on GitHub Overview
Aiready best practices guide for writing AI-friendly codebases. It focuses on reducing semantic duplicates, context fragmentation, and naming inconsistencies to improve how AI assistants understand and maintain code.
How This Skill Works
The guide defines core capabilities—AI Signal Clarity, Context Optimization, Pattern Detection, Consistency, and Health Assessment—and provides practical rules and commands to enforce them. Teams apply these checks during writing, PR reviews, and refactoring to improve AI comprehension.
When to Use It
- When writing new code
- During pull request reviews
- During refactoring for AI adoption
- When debugging AI assistant confusion
- During regular codebase health audits with aiready scan
Quick Start
- Step 1: Run a health check with npx @aiready/cli scan .
- Step 2: Detect patterns and inconsistencies with npx @aiready/cli patterns . and npx @aiready/cli consistency .
- Step 3: Apply AI-friendly refactors to naming, context, and documentation
Best Practices
- Clarify AI signals by removing ambiguity in identifiers and comments
- Consolidate semantic duplicates to avoid redundancy
- Minimize context fragmentation by reducing cross-file dependencies
- Maintain consistent naming and architectural patterns
- Run proactive health checks with aiready scan and address gaps
Example Use Cases
- Detecting and consolidating duplicate function names across modules
- Renaming ambiguous variables to clearer, AI-friendly terms
- Reducing long call chains to limit context window usage
- Aligning naming conventions across services
- Running aiready scan for ongoing health insights
