# Best Practice Guides

Best practices and integration guides for AI agents working with development tools and workflows. These guides ensure consistent, high-quality output across AI tools (Claude Code, Cursor, Codex CLI, GitHub Copilot).

## Available Guides

| Guide                                          | Purpose                                                      | Target Audience                                | When to Apply                                                                 |
| ---------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------- | ----------------------------------------------------------------------------- |
| [agents.sonar.md](agents.sonar.md)             | SonarQube/SonarCloud integration for automated code quality  | AI agents, code reviewers                      | Projects using SonarQube for quality gates and security scanning              |
| [agents.markdown.md](agents.markdown.md)       | Markdown formatting standards for AI-generated documentation | AI agents, documentation reviewers             | Documentation >50 lines (READMEs, guides, API docs, troubleshooting)          |
| [agents.gotask.md](agents.gotask.md)           | GoTask usage guide for task automation workflows             | AI agents, task developers                     | Any project using Taskfile.yml for build automation and development workflows |
| [agents.task-master.md](agents.task-master.md) | Task Master AI integration for structured development cycles | AI agents, project managers                    | Projects using Task Master for iterative task management via MCP              |
| [github-mcp.md](github-mcp.md)                 | GitHub MCP server integration for repository operations      | AI agents, developers configuring GitHub tools | Projects requiring GitHub integration (PRs, issues, repo management)          |

## Guide Summaries

### agents.sonar.md

Enables automated SonarQube/SonarCloud integration for code quality and security analysis. Teaches AI agents to download analysis results programmatically, review security hotspots, fix issues automatically, and integrate with `/pr:fix` workflow without requiring manual UI access.

### agents.markdown.md

Teaches AI agents to create readable documentation by showing structure and concepts upfront while hiding implementation details in collapsible sections. Applies to READMEs, API docs, and technical guides over 50 lines.

### agents.gotask.md

Establishes GoTask as the standard for build automation and development workflows. Covers task namespacing, dependencies, variables, and integration with secret management. Used for build/test automation and code quality checks.

### agents.task-master.md

Provides structured task management through MCP integration. Guides AI agents on breaking down complex features, tracking implementation progress, managing task dependencies, and enabling research-backed planning for technical decisions.

### github-mcp.md

Defines controlled GitHub access through MCP server with limited permissions. Ensures AI agents can read repositories and create pull requests while protecting sensitive operations. Covers token management and secure configuration.

## Usage by AI Agents

These guides are automatically installed and configured by the AI Toolkit installer. The installer references these guides in AI tool configuration files, ensuring consistent best practices across all supported agents.

### Claude Code

**Auto-Configured**: Referenced in `CLAUDE.md` and loaded automatically.

**How It Helps**:

- Generates well-structured documentation following markdown standards
- Uses GoTask commands for build automation instead of direct shell commands
- Integrates Task Master MCP for structured task management
- Accesses GitHub via MCP with limited permissions (read repos, create PRs)

### Cursor IDE

**Auto-Configured**: Installer adds rules to `.cursor/settings.json`.

**How It Helps**:

- Applies markdown standards when generating documentation
- Suggests GoTask commands for common development tasks
- Integrates with Task Master for project planning
- Restricts GitHub operations to safe, limited scope

### Codex CLI

**Auto-Configured**: Installer adds references to Codex configuration.

**How It Helps**:

- Maintains consistent documentation format across CLI sessions
- Recommends GoTask over ad-hoc shell scripts
- Connects to Task Master MCP for task tracking
- Uses GitHub MCP with controlled permissions

### GitHub Copilot

**Auto-Configured**: Referenced in `.github/copilot-instructions.md` if available.

**How It Helps**:

- Suggests markdown formatting that matches project standards
- Recommends GoTask commands in inline suggestions
- Limited integration (no native MCP support)
- Follows GitHub best practices from guide

## Creating New Guides

When adding a new best practice guide:

1. Create a new `agents.<topic>.md` file in this directory
2. Include clear sections:
   - Purpose and target audience
   - Core principles
   - Key guidelines
   - Example use cases
   - When to apply / when NOT to apply
   - Practical examples
3. Update this README:
   - Add entry to Available Guides table
   - Add Quick Reference section
   - Add to "When to Apply These Guides" section
4. Reference in [CLAUDE.md](../../CLAUDE.md) if applicable

## Related Documentation

- [Slash Commands](../commands/README.md) - Reusable command templates for AI agents
- [Task Library](../../tasks/README.md) - GoTask automation scripts and utilities
- [QA Standards](../QA.md) - Quality assurance guidelines and testing practices
- [Installation Guide](../installer.md) - AI Toolkit installation and configuration
- [1Password Integration](../1password.md) - Secret management setup