AI-Assisted Software Engineering

Prompting Intentionally

A prompt is a specification. The quality of the output is bounded by the quality of the input. Every strong prompt answers four questions.

Weak prompt// No context, no constraint, vague goal
"Add authentication to my app."

// Result: boilerplate that may not fit your
// stack, overwrite existing code, or add
// libraries you did not want.

Strong prompt// Context + Constraint + Goal + Format
"This is a Laravel 11 API. Auth uses Sanctum
 and is already wired. Do not touch AuthController.
 Add a POST /webhooks/payment endpoint that:
 validates JSON body (event_id, payment_id,
 event, amount, currency), upserts a Payment
 model, and returns {status:'received'}.
 Show only the controller method and route."

Planning Before You Build

AI writes code faster than you can think through architecture. Slow down at design time — that is where AI is most powerful and where skipping it costs the most.

Cursor, Claude Code & Codex

Three tools, three interaction models. They complement each other — knowing when to reach for each one multiplies your output.

MCP — Model Context Protocol

MCP is an open standard that lets AI tools talk to external systems in a structured, composable way. Instead of copy-pasting context into prompts, the model pulls exactly what it needs.

How Subagents Work

A subagent is an AI agent spawned by a parent agent to handle a focused sub-task. The parent orchestrates; subagents execute. This enables parallelism, context isolation, and specialization.

Project-Scoped Skills

Skills are reusable prompt templates committed to the repo. Call them as slash commands — /playwright, /laravel-feature, /vue-component — and the model follows your team's conventions automatically.

Anatomy of a skill file

.claude/commands/your-skill.md---
description: Short description shown in the /command list
allowed-tools: Read, Write, Bash, Glob, Grep    # tools the agent may use
---

# Context
What the agent needs to know about this project before starting.
Stack, conventions, file structure, patterns to follow.

# Instructions
Step-by-step directions. Be as specific as your conventions require.
Reference actual paths, class names, and patterns from this repo.

# Task
$ARGUMENTS    # replaced at runtime with what you type after the command

Skill: Playwright E2E Tests

Invoke /playwright <describe the flow>. The agent reads existing test patterns, creates a Page Object Model, and writes a fully structured E2E test.

---
description: Generate a Playwright E2E test with Page Object Model for a given user flow
allowed-tools: Read, Write, Glob, Bash
---

# Context
This project uses Playwright with TypeScript. Tests live in `tests/e2e/`.
Page Object Models live in `tests/e2e/pages/`.
Use `data-testid` attributes as selectors — never CSS classes or XPath.
Follow Arrange-Act-Assert. One behaviour per test() block.

# Instructions
1. Read two or three existing tests in `tests/e2e/` to understand the project's style.
2. Identify whether a POM for the target page already exists. If not, create one.
   - POM class name: `{PageName}Page` extending `BasePage`
   - Expose locators as readonly properties, actions as methods
3. Write the test file using test.describe + test() blocks.
4. Use await expect(page).toHaveURL() and role-based locators where possible.
5. Run `npx playwright test --headed {file}` and fix any failures before finishing.

# Task
Write a Playwright E2E test for the following flow:
$ARGUMENTS

Skill: Laravel Feature

Invoke /laravel-feature <describe the feature>. The agent scaffolds the full vertical slice — migration, model, request, service, controller, route, and feature test — all following your team's conventions.

---
description: Scaffold a complete Laravel feature: migration, model, request, service, controller, route, and test
allowed-tools: Read, Write, Bash, Glob, Grep
---

# Context
Laravel 11, PHP 8.3. Architecture: thin controllers → Service classes → Eloquent models.
- Controllers: `app/Http/Controllers/` — no business logic, only HTTP concerns
- Form Requests: `app/Http/Requests/` — all validation lives here
- Services: `app/Services/` — all business logic, injected via constructor
- Models: typed Eloquent properties, $fillable defined, no logic beyond scopes
- Routes: registered in `routes/api.php` or `routes/web.php` using Route::apiResource
- Tests: `tests/Feature/`, use RefreshDatabase, test happy path + validation errors

# Instructions
1. Read `app/Services/` and one existing controller to confirm current patterns.
2. Create the migration. Run php artisan migrate to verify it is valid.
3. Generate the Model with fillable, casts, and any obvious relationships.
4. Create the Form Request with validation rules. Reject clearly invalid input.
5. Create the Service class injected into the controller via constructor.
6. Create the Controller with index / store / show / update / destroy as needed.
7. Register the route. Run php artisan route:list to confirm.
8. Write a Feature test covering: successful creation, validation failure, and not-found.
9. Run php artisan test --filter {FeatureName}. Fix any failures.

# Task
$ARGUMENTS

Skill: Vue Component

Invoke /vue-component <describe the component>. The agent produces a typed <script setup> component and extracts reusable logic into a composable when the state warrants it.

---
description: Generate a Vue 3 component (script setup + TypeScript) and composable if logic is reusable
allowed-tools: Read, Write, Glob
---

# Context
Vue 3 with <script setup> and TypeScript. Components in `src/components/` (PascalCase).
Composables in `src/composables/use{Name}.ts`. Pinia for global state.
- Props: defineProps<{ prop: Type }>() — always typed, never PropType
- Emits: defineEmits<{ eventName: [payload: Type] }>()
- Expose nothing by default; use defineExpose only when the parent truly needs it
- Styles: <style scoped> with BEM-like class names
- No inline styles; no style bindings unless driven by a prop value (e.g. width)

# Instructions
1. Read 1–2 existing components in `src/components/` to match the project's conventions.
2. Decide whether state and async logic should live in the component or a composable.
   - Extract to composable if: logic is used in >1 place OR the component exceeds ~80 lines.
3. Write the `{Name}.vue` file with props, emits, slots, and template.
4. If a composable is warranted, write `use{Name}.ts` and import it in the component.
5. Add a brief // Usage comment at the top of the component showing a minimal example.

# Task
$ARGUMENTS