architecture

Engineering AI Agents

AI agents for engineering: code assistance, PR review, documentation generation, and incident analysis. Includes off-the-shelf options, custom build approaches, and training examples.

Overview

Engineering efficiency focuses on code generation, debugging, documentation, code review, and architecture decisions. The key is augmenting judgment, not replacing it.

Efficiency Potential: 6-8 hrs/week at Adoptive tier; 10-12 hrs at Transformative

Agent Summary

Agent Efficiency Target Complexity Priority
20-40% coding time reduction Low High
50% review time reduction Medium High
Auto-generated from code Medium Medium
30 min β†’ 10 min triage Medium Medium

Code Assistant

Problem Statement

Engineers spend significant time on boilerplate, syntax lookup, and translating intent to code. AI can handle mechanical translation while engineers focus on architecture and logic.

Efficiency Target: 20-40% coding time reduction depending on task type

Off-the-Shelf Options

Tool Capability Pricing
GitHub Copilot Inline completions, chat $19/user/mo
Cursor AI-native IDE, multi-file edits $20/user/mo
Claude Code Terminal-based coding agent API pricing
Amazon CodeWhisperer AWS-integrated Free tier
Codeium Free completions, IDE plugins Free / $12/mo

High-Value Use Cases

1. BOILERPLATE GENERATION
   - Test scaffolding
   - API endpoint templates
   - Data model definitions
   - Configuration files

2. LANGUAGE/FRAMEWORK TRANSLATION
   - "Convert this Python to TypeScript"
   - "Rewrite using async/await"
   - "Port to React hooks"

3. DOCUMENTATION
   - Docstrings from code
   - README generation
   - API documentation

4. CODE EXPLANATION
   - "Explain what this regex does"
   - "What's the time complexity?"
   - "Why might this cause a memory leak?"

5. DEBUGGING ASSISTANCE
   - "Why might this throw X error?"
   - "Find the bug in this function"
   - Error message interpretation

Prompting Patterns

PATTERN 1: Specification-First
"Write a function that:
- Takes: [input types and constraints]
- Returns: [output type and format]
- Handles: [edge cases]
- Example: [input] -> [output]"

PATTERN 2: Context-Rich
"In a [framework] application using [patterns],
create a [component type] that [behavior].
Follow the style of [existing file reference].
Include error handling for [scenarios]."

PATTERN 3: Test-First
"Given this test:
[test code]
Write the implementation that makes it pass."

PATTERN 4: Refactor
"Refactor this code to:
- [specific improvement]
- [maintain behavior]
- [follow pattern]
Keep the same interface."

PR Review Assistant

Problem Statement

Code review is essential but time-consuming. Reviewers catch bugs, style issues, and logic errors while also mentoring. AI can handle routine checks, freeing reviewers for high-judgment review.

Efficiency Target: Review time 50% reduction; higher quality catches

Off-the-Shelf Options

Tool Capability Pricing
CodeRabbit Automated PR review $15/user/mo
Codacy Code quality + security $15/user/mo
GitHub Copilot PR PR summaries Included
Graphite PR workflow + AI review $30/user/mo

Training Example: PR Review

Review this pull request and provide feedback.

PR TITLE: {{pr_title}}
PR DESCRIPTION: {{pr_description}}
AUTHOR: {{author}}
FILES CHANGED: {{files_list}}

DIFF:
{{diff_content}}

CONTEXT:
- Repository: {{repo}}
- Main language: {{language}}
- Key patterns: {{patterns_used}}

REVIEW CRITERIA:

1. CORRECTNESS
   - Logic errors
   - Edge cases not handled
   - Potential bugs

2. SECURITY
   - Injection vulnerabilities
   - Auth/authz issues
   - Data exposure risks

3. PERFORMANCE
   - N+1 queries
   - Unnecessary computation
   - Memory concerns

4. MAINTAINABILITY
   - Code clarity
   - Naming
   - Complexity

5. TESTS
   - Coverage gaps
   - Test quality
   - Missing edge cases

OUTPUT FORMAT:

## PR Review: {{pr_title}}

### Summary
[1-2 sentence overview]

### Must Fix (Blocking)
- [ ] **File:line** - [issue and why it's blocking]

### Should Fix (Non-blocking)
- [ ] **File:line** - [issue and recommendation]

### Suggestions (Optional)
- [ ] **File:line** - [improvement idea]

### Questions
- [Clarifications needed from author]

### What's Good
- [Positive callouts]

Architecture Pattern

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ PR       │──►│ Static   │──►│ AI       │──►│ Summary  β”‚
β”‚ Webhook  β”‚   β”‚ Analysis β”‚   β”‚ Review   β”‚   β”‚ Generatorβ”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                    β”‚              β”‚              β”‚
                    β–Ό              β–Ό              β–Ό
              [Lint/Type     [Logic/       [PR Comment
               Errors]        Security]      Posted]

Documentation Generator

Problem Statement

Documentation is perpetually outdated because it's tedious to write and maintain. Engineers write code, not docs. But good docs reduce support burden and improve adoption.

Efficiency Target: Docs generated from code automatically; maintained with changes

Training Example: API Documentation

Generate API documentation from this code.

CODE:
{{code_content}}

EXISTING DOCS (if any):
{{existing_docs}}

DOCUMENTATION STYLE: {{style_guide}}

GENERATE:

## {{endpoint_or_function_name}}

### Description
[What this does and when to use it]

### Endpoint
`{{method}} {{path}}`

### Authentication
[Required auth method]

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
[Extracted from code]

### Request Body
```json
{
  // Schema with descriptions
}

Response

Success (200)

{
  // Response schema with example
}

Errors

Code Description
[Common error responses]

Example

Request:

curl -X {{method}} ...

Response:

{
  // Example response
}

---

## Incident Analysis Assistant

### Problem Statement

When incidents occur, engineers scramble to understand logs, metrics, and system state. Root cause analysis is time-consuming and often incomplete.

**Efficiency Target:** Incident triage from 30 min β†’ 10 min; better RCA documentation

### Training Example: Incident Triage

Analyze this incident and suggest investigation paths.

INCIDENT SUMMARY:

  • Severity: {{severity}}
  • Reported: {{timestamp}}
  • Symptoms: {{symptoms}}
  • Affected: {{affected_systems}}

LOGS: {{relevant_logs}}

METRICS: {{metrics_data}}

RECENT CHANGES: {{recent_deployments}}

ERROR MESSAGES: {{errors}}

GENERATE:

Incident Triage: {{incident_id}}

Quick Assessment

  • Likely scope: [contained / spreading / unknown]
  • User impact: [description]
  • Urgency: [immediate / soon / can wait]

Pattern Recognition

[Match against known incident patterns]

  • This looks similar to: [past incidents if recognizable]
  • Key indicators: [what signals point to cause]

Investigation Paths (Prioritized)

  1. Most Likely: {{hypothesis_1}}

    • Evidence: [what points here]
    • Check: [specific command/query to run]
    • If confirmed: [immediate action]
  2. Possible: {{hypothesis_2}}

    • Evidence: [what points here]
    • Check: [specific command/query to run]
  3. Less Likely: {{hypothesis_3}}

    • Evidence: [what points here]
    • Check: [if other paths don't pan out]

Immediate Actions

  • [Mitigation step if obvious]
  • [Communication needed]
  • [Escalation if required]

Timeline Reconstruction

[Sequence of events from available data]


### Architecture Pattern

Uses ENT-RAG for similar incident retrieval:

```python
# Retrieve similar past incidents
similar_incidents = incident_vectorstore.similarity_search(
    f"Error: {error_message} Service: {service_name}",
    k=5,
    filter={"resolution": {"$exists": True}}  # Only resolved incidents
)

# Include in analysis context
analysis_prompt = f"""
Current incident: {incident_summary}

Similar past incidents:
{format_similar_incidents(similar_incidents)}

Generate triage analysis...
"""

Chains

PR Review Pipeline

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ PR       │──►│ Static   │──►│ AI       │──►│ Summary  β”‚
β”‚ Webhook  β”‚   β”‚ Analysis β”‚   β”‚ Review   β”‚   β”‚ Generatorβ”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Incident Response Chain

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Alert    │──►│ Log      │──►│ Hypothesis│──►│ Runbook  β”‚
β”‚ Trigger  β”‚   β”‚ Analyzer β”‚   β”‚ Generator β”‚   β”‚ Suggesterβ”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                  β”‚
                                  β–Ό
                          β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                          β”‚ Similar Incident β”‚
                          β”‚ RAG Retrieval    β”‚
                          β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜