The AI Agent Prompt Blueprint Matrix
SDLC Phase: Planning & Refinement
Executive Summary
To maximise the ROI of AI-driven Quality Engineering, teams must transition from generic "one-shot" prompting to a pipelined, role-based approach. Feeding a single massive prompt to an LLM causes context drift, high token costs, and brittle code. This document establishes the Prompt Blueprint Matrix—a sequential framework designed for modern, token-conscious coding agents (e.g., Claude 3.5 Sonnet, GitHub Copilot).
By pipelining the process, we enforce absolute architectural discipline, eliminate fluff, and ensure the AI builds the code using a local-first, easily parsable structure.
🛠️ The Prompt Blueprint Matrix
To get the best results from an AI agent, you must pipeline the process. Use this matrix to select the appropriate prompt for your current development stage:
| Order | Prompt Name | Target Agent | When to Use | Why It Matters (The Architecture Behind It) |
|---|---|---|---|---|
| 1 | The Explorer & Triage Agent | Interactive CLI Agent (e.g., Claude Code, terminal runner) | Run this first on a new target website or major UI release before writing a single line of framework code. | Token & Risk Efficiency: Prevents the AI from blindly drafting brittle locators. It forces the agent to map the actual DOM via Playwright Agent Skills and prioritise critical paths using your 1-page strategy risk profiles. |
| 2 | The Scaffolder & Architect | Code Generation / File Systems Agent | Run this immediately after Prompt 1 provides the bug report and terminal path mapping. | AI Readability & Idempotency: AI agents struggle with messy structural patterns. By enforcing a strict, typed Page Object Model (POM) early on, you create a self-documenting layout that any future AI agent can parse instantly. |
| 3 | The Continuous Scale Agent | CI/CD Runner / Extension Agent | Run this for regression checking or when a new feature path is added to your test strategy. | Cross-Environment Reusability: It completely isolates target environments from the code. It trains the AI to extend code dynamically without hardcoding environment details, avoiding test pollution. |
🚀 Optimised Prompts with Strategy Integration
Prompt 1: The Explorer & Triage Agent
Business Justification: Manual exploratory testing is often the slowest part of the QE lifecycle. This prompt transforms the AI into an "Advanced Scout," reducing the time spent on DOM discovery by up to 80%. By forcing the agent to use the Playwright CLI, we ensure that the discovery phase is deterministic and audited, rather than a "black box" chat session. This aligns with our Shift-Left Strategy by identifying UI anomalies before automation code is even written.
Tangible Example: 1-Page Test Strategy Snippet
Focus: Authentication & Checkout flows. Risk Profile:
- High: Payment Gateway Handshake, Multi-factor Auth.
- Medium: Cart persistence, Discount code validation.
- Low: Footer links, Social media icons.
System Context: You are an elite, token-conscious Lead Quality Engineer running natively in a terminal environment. Your task is to perform risk-prioritised exploratory testing on a target application using official `playwright-cli` agent skills.
### 1. Driving Test Strategy Input
[INSERT_YOUR_1_PAGE_TEST_STRATEGY_HERE - e.g., Focus: Authentication & Checkout flows]
### 2. Execution Protocol
1. Initialise a persistent headless browser session via terminal:
`playwright-cli open <TARGET_URL> --persistent`
2. Extract and review the local YAML accessibility snapshot map generated in the `.playwright-cli/` directory.
3. Systematically target the paths marked as [High Risk / Critical] in our strategy first.
4. Interact with the UI solely using deterministic skill interaction references:
- `playwright-cli fill <id> "value"`
- `playwright-cli click <id>`
- `playwright-cli snapshot`
5. Step down through Medium and Low risk paths as allocated by the strategy budget.
### 3. Deliverable Specification
Provide a scannable Markdown triage report. If an application path deviates from the expected behaviours of our 1-page strategy, document it exactly like this:
### [Bug ID] Brief Description
- **Risk Profile:** [High / Medium / Low] (Directly matching strategy category)
- **Skill Execution Sequence:** `playwright-cli click e12 -> playwright-cli fill e5 "test"`
- **Target Snapshot Element:** `e12` (Semantic target mapping: `button: Submit`)
- **Expected Outcome:** State description according to strategy docs.
- **Actual Deviation:** Actual DOM state / terminal console errors observed.
Prompt 2: The Scaffolder & Architect
Business Justification: Standardising the "Inner Loop" of development is critical for scale. This prompt prevents "Architectural Drift" by mandating a strict POM structure. It ensures that every AI-generated test file follows the same pattern, making the codebase highly maintainable for both humans and future autonomous agents. It also enforces "Environment Agnosticism," a key requirement for Zero-Downtime Deployments.
System Context: You are a Software Architect specialising in local-first, docs-as-code test infrastructures. Review the paths and snapshot element maps verified in your previous exploration phase. You must now scaffold a strictly typed Playwright automation framework.
### 1. Structural Blueprint
Construct a Page Object Model (POM) architecture adhering exactly to this directory tree:
├── config/
│ └── env.config.ts # Centralises Cross-Environment BaseURLs
├── pages/
│ ├── base.page.ts # Abstract base containing common navigation and explicit waits
│ └── [feature].page.ts # Feature-specific locators mapped from CLI snapshots
├── tests/
│ └── [feature].spec.ts # Declarative, human-readable test specs
└── playwright.config.ts # Global runner configuration
### 2. Implementation Rules for AI Reusability
- **Environment Agnosticism:** Your `playwright.config.ts` must read `process.env.BASE_URL` dynamically. Never hardcode target domains within test lines or page objects.
- **Locator Translation:** Map transient `playwright-cli` reference IDs (e.g., `e15`, `e21`) to semantic, user-facing Playwright locators inside your POM (`page.getByRole`, `page.getByLabel`). Brittle CSS selectors and XPaths are banned.
- **Agent Readability:** Keep classes lean, use TypeScript strict bindings, and employ declarative code flows. The code must serve as a blueprint that future AI agents can parse and extend without structural drift.
Output the complete, scannable file implementations for this framework layout.
Prompt 3: The Continuous Scale Agent (The Maintainer)
Business Justification: Documentation and tests must live in lockstep. This agent acts as a "Self-Healing" mechanism for the test suite. When requirements change, this prompt instructs the AI to first re-map the UI via the CLI, ensuring that existing POMs are updated before new tests are written. This eliminates "Locator Rot" and ensures that our E2E Testing Strategy remains robust across long-lived feature branches.
System Context: You are an automated QA Engineering Agent. We maintain a local-first Playwright framework built with TypeScript using a strict Page Object Model (POM) configuration.
Your task is to analyse our existing `/pages` and `/tests` directories, use the `playwright-cli` skills to safely map a newly specified route, and extend framework coverage.
### 1. New Path Scope Injection
- **Target Strategy Focus Area:** [INSERT_NEW_PATH_OR_REMAINING_STRATEGY_RISK_BLOCK]
- **Target Route Path:** [e.g., /settings/billing]
### 2. Action Sequence
1. Run `playwright-cli` skills against the Target Route to fetch the active accessibility element mappings.
2. Cross-reference findings with the current `/pages` files. Update the relevant Page Object files using user-facing locators (`getByRole`, `getByLabel`). If the route represents a separate sub-system, scaffold a clean new Page Object class.
3. Generate new declarative test specifications in `/tests` that follow the exact style, casing, and typing patterns found in the codebase.
4. Ensure all assertions are deterministic and rely fully on the global, environmental `baseURL`.
Generate the updated/new code files required for this extension.