DOCSEARCHbyAlgolia
Submit Docs

Software Mansion Agentic Engineering Guide

website·Indexed 39 days ago

https://agentic-engineering.swmansion.com

Practical guidance for setting up and scaling agentic engineering workflows in real software projects. Covers designing bounded loops, harness engineering with AGENTS.md and Model Context Protocol (MCP), spec-driven development, security models for coding agents, and strategies for running multiple agents in parallel.

Tokens
18.5K
Snippets
33
Records
123
Agent score
58%

What's inside Software Mansion Agentic Engineering Guide

  1. Overview of Spec-Driven Development

    Spec-Driven Development is a methodology that places requirements at the center of the development process. Instead of focusing on implementation, it focuses on defining, managing, and enforcing a 'solution space'—the boundaries within which a product must operate. This approach prevents AI agents from making incorrect assumptions (treating a single implementation as the absolute requirement) or becoming overly defensive/aggressive due to a lack of context in new conversations.

  2. Understand the project source structure for screens, routes, and navigators

    The project organizes its navigation and screen architecture into three primary files within the src directory: SCREENS.ts for screen name constants, ROUTES.ts for route definitions and builders, and NAVIGATORS.ts for the overall navigator configuration.
    // src/SCREENS.ts: Screen name constants
// src/ROUTES.ts: Route definitions and builders
// src/NAVIGATORS.ts: Navigator configuration

  3. Understand the Lethal Trifecta threat model for coding agents

    The 'Lethal Trifecta' is a security risk model for AI agents that occurs when a single agent run possesses three specific capabilities simultaneously:

    1. Access to private data: The ability to read proprietary codebases or local machine data.
    2. Exposure to untrusted content: The ability to process malicious input from web search results, grepped files, MCP tool descriptions, or third-party 'Skills'.
    3. External communication/side effects: The ability to send data outward or trigger meaningful changes in the environment.

    When these three overlap, an attacker (or a careless user) can use prompt injection to steal or modify private data. Breaking any one side of this triangle reduces the risk, though for coding agents, access to private data is usually a requirement, making the other two (untrusted content and outward communication) the primary targets for defense.

  4. Manage agent threads and model context windows

    Coding agents transform agent threads into input strings for LLMs. The context window is the maximum length of this input string the model can ingest. To ensure reliability and avoid hitting hard limits, agents often reduce the usable window slightly to reserve space for tail system messages or compaction prompts. To maintain performance and reliability, it is recommended to keep threads short.

  5. Define the solution space using Spec-Driven Development

    In Spec-Driven Development (SDD), a specification is a description of a system's valid solution space. Its purpose is to concisely define the boundaries that both AI agents and human developers must adhere to, treating the codebase as one concrete implementation within that defined space.

  6. Prevent architectural decay (spaghetti code) in agentic engineering

    Agents are often rewarded for task completion rather than long-term architecture. To maintain code quality when using multiple agents:

    • Modularize: Use small modules with strict boundaries and predictable I/O.
    • Enforce Invariants: Use strict typing, assertions, and comprehensive tests rather than relying on documentation.
    • Mechanical Enforcement: Direct agents to write their own linters and CI jobs to enforce patterns.
    • Knowledge Accessibility: Ensure all critical knowledge is stored as files in the repository or accessible via MCP (Model Context Protocol), as agents lack long-term memory.
    • Align with Model 'Taste': Avoid enforcing strict human stylistic preferences if they conflict with the libraries and patterns agents naturally prefer; aligning the codebase with model mindsets improves agent accuracy.

  7. Compare API pricing vs. App subscriptions

    There are two primary ways AI tools are priced:

    1. API Pricing: Pay-per-token. This is used for direct integration into applications and provides raw API credits.
    2. App Subscriptions: A flat monthly fee for usage within a specific product (e.g., ChatGPT, Claude, Cursor). These usually have fair-use limits or caps and do not provide raw API credits for external apps.

  8. Understand the principles of Agentic Engineering

    Agentic engineering is a professional software development approach where AI agents act as active collaborators rather than simple snippet generators. Agents are capable of inspecting repositories, using tools, proposing changes, and executing multi-step tasks. To maintain engineering standards (avoiding 'vibe coding'), the workflow must include human responsibility for outcomes, reviewable changes, quality gates, clear prompts, structured projects, and repeatable team practices.

  9. Capabilities of modern AI coding agents

    Modern AI coding agents provide a wide range of capabilities to assist developers in the software development lifecycle, including:

    • Codebase Management: Independently indexing, understanding, and navigating local codebases.
    • External Integration: Searching the internet and connecting to external services (e.g., via Model Context Protocol/MCP).
    • Debugging & Analysis: Instrumenting code for debugging (such as adding console.log statements) and analyzing visual assets like screenshots, videos, and Figma designs.
    • Planning & Execution: Preparing detailed implementation plans and automatically testing changes, including browser-based testing.

  10. Extend agent capabilities with Model Context Protocol (MCP)

    The Model Context Protocol (MCP) allows AI applications to connect to local or remote data sources, tools, and workflows. MCP servers add capabilities beyond the filesystem and bash commands.

    • Local MCPs: Run locally (e.g., @playwright/mcp) to interact with the local environment.
    • Remote MCPs: HTTP-based servers (e.g., Linear MCP) that connect to remote services.

    Key Considerations:

    • Authentication: MCP supports API keys and OAuth via the harness UX.
    • Performance: Too many MCP servers can overload the system prompt, slowing down the harness and reducing agent capability.
    • Composability: Unlike Bash, MCP outputs cannot be easily piped into tools like awk or jq unless the MCP server is wrapped in a CLI using mcporter.

  11. Implement Harness Engineering for coding agents

    Harness engineering is the practice of improving a coding agent's output quality and reliability by shaping the software environment around it. Instead of relying solely on chat prompts, developers shape the 'harness'—which includes instructions, tools, context, hooks, and integrations—to make correct agent behavior easier and more repeatable.

  12. Understand the components of an agent loop

    An agent loop is a repeated workflow designed to replace manual coordination. Unlike a simple timer, a loop inspects fresh evidence at each turn to decide the next move. A standard loop consists of a trigger, context gathering, a work step, a verification step, and a stop condition.
    while not stop_condition():
    context = gather_context()
    result = run_agent(context)
    evidence = verify(result)
    record_state(result, evidence)