Best Practices Advanced

Get the most out of the Coding Agent by following these best practices for issue writing, repository setup, security, cost management, and team scaling. This lesson also covers common pitfalls and frequently asked questions.

Writing Effective Issues for the Agent

The quality of the agent's output is directly proportional to the quality of the issue description. Follow these guidelines consistently:

Repository Setup for Best Results

Your repository structure significantly impacts the agent's effectiveness. Invest in these areas for the best results:

Test Coverage

Good test coverage is the single most important factor for agent success. Tests serve as a safety net that lets the agent validate its changes.

# Minimum recommended test coverage for agent repos:
# - 70%+ line coverage overall
# - 90%+ on critical business logic
# - Unit tests for all services and utilities
# - Integration tests for API endpoints
# - Test commands documented in package.json / Makefile

# package.json scripts example:
{
  "scripts": {
    "test": "jest",
    "test:coverage": "jest --coverage",
    "test:watch": "jest --watch",
    "lint": "eslint src/",
    "typecheck": "tsc --noEmit"
  }
}

CI/CD Pipeline

A robust CI pipeline gives the agent fast feedback on its changes. Include:

• Linting — catches style and formatting issues
• Type checking — catches type errors (TypeScript, mypy, etc.)
• Unit tests — validates individual components
• Integration tests — validates system behavior
• Coverage reporting — tracks whether new code is tested

Clear Project Structure

Consistent, well-organized code helps the agent navigate your codebase and follow existing patterns:

# Clear, conventional structure helps the agent
src/
  routes/          # API route handlers
  services/        # Business logic
  models/          # Data models
  utils/           # Shared utilities
  middleware/      # Express/Koa middleware
tests/
  routes/          # Mirrors src/ structure
  services/
  utils/
  mocks/           # Shared test mocks
  fixtures/        # Test data
.github/
  copilot-setup-steps.yml
  workflows/
    ci.yml

Documentation

Keep these files up to date to help the agent understand your project:

• README.md — Project overview, setup instructions, architecture notes
• CONTRIBUTING.md — Code style, PR process, testing requirements
• .github/copilot-setup-steps.yml — Environment setup for the agent
• Inline comments — Non-obvious business logic should be commented

Security Considerations

The Coding Agent runs in a sandboxed environment, but you should still follow security best practices:

# .github/CODEOWNERS
# Require senior dev review for security-critical paths

src/auth/          @your-org/security-team
src/payments/      @your-org/security-team
src/middleware/auth*  @your-org/security-team
.github/           @your-org/platform-team
*.yml              @your-org/platform-team

Cost Management

The Coding Agent uses compute resources and LLM tokens. Here are strategies to manage costs effectively:

When to Use the Agent vs Manual Coding

The Coding Agent is not the right tool for every task. Use this decision framework:

Scaling AI-Assisted Development

As your team gets comfortable with the Coding Agent, here is how to scale its usage effectively:

1. Standardize issue templates

   Create GitHub Issue templates specifically for agent tasks. Include sections for context, requirements, acceptance criteria, file references, and testing instructions.

2. Establish review guidelines

   Define what reviewers should check on agent PRs: correctness, test quality, security, performance, and adherence to coding standards.

3. Track metrics

   Measure time-to-merge for agent PRs vs human PRs, PR acceptance rate, number of review iterations, and issues resolved per week.

4. Build a knowledge base

   Document what types of tasks work well with the agent and which don't. Share learnings across the team.

5. Invest in test infrastructure

   Better tests lead to better agent results. Prioritize test coverage improvements as a multiplier for agent effectiveness.

Common Pitfalls

Frequently Asked Questions