A structured approach to AI-assisted development — where we define the problems and the agent executes the solutions. We stay in control of every decision.
We still own every line of code. The agent handles the repetitive execution — we focus on the thinking, the architecture, and the decisions that matter.
Global instructions live in a dedicated repo and flow into every project as a git submodule. Each project adds its own layer on top.
.vscode/settings.json
wires all instruction files into Copilot automatically on clone. Zero manual setup.specs/.
Specs are business-focused. We describe what a feature does — not how it's built. The agent figures out the technical implementation from our instructions.
specs/,
committed and versioned with the code. No endpoints, no module names, no DTOs — that belongs in our
instructions. The out-of-scope field is critical: it prevents the agent from touching
anything outside the defined boundaries.
How our three layers look for a real project — the Tracking Service backend with Users and Shipments modules.
# Global Backend Instructions ## Stack - NestJS — TypeScript strict - MongoDB with Mongoose - Jest for testing - REST API with versioning ## Architecture - Feature-based module structure - One module per domain - Repository pattern for data access - DTO-based input/output contracts ## Agent Behavior - Always output a step-by-step plan before writing any code - Wait for explicit approval before starting execution - Execute one step at a time, show the diff, wait before proceeding - Never modify files outside the scope defined in the spec - If something in the spec is ambiguous, ask before assuming ## Process - All features start from a spec - CI must pass before merge
# Project: Tracking Service A logistics backend — manages users and tracks shipments end to end. ## Modules - Users — registration, authentication, profile - Shipments — creation, tracking, status lifecycle ## Domain Rules - Every shipment belongs to a user - Shipment status follows a strict lifecycle - All timestamps in UTC - Soft delete across all collections ## Shipment Status Lifecycle pending → picked_up → in_transit → out_for_delivery → delivered - Status cannot go backwards - Cancellation allowed from pending or picked_up only ## Collections - users - shipments - shipment_events ## Environment - MongoDB Atlas - JWT authentication — RS256 - Secrets via environment variables
## Feature: User Registration ### Business Logic - A user registers with full name, email, password - Email must be unique across the system - On success, user receives a confirmation email - Account is inactive until email is confirmed ### Rules - Duplicate email returns a clear business error - Unconfirmed accounts cannot log in - Registration is open — no invite required ### Edge Cases - Registering with an already confirmed email - Re-registering with an unconfirmed email → resend confirmation, do not create duplicate
## Feature: User Authentication ### Business Logic - A confirmed user logs in with email and password - On success, receives access token and refresh token - Access token has a short lifespan - Refresh token allows silent renewal without re-login - Logout invalidates the refresh token ### Rules - Unconfirmed accounts rejected with a clear message - Wrong credentials do not reveal which field is wrong - Refresh token is single-use — rotates on each renewal ### Edge Cases - Using an already-rotated refresh token → invalidate the entire session
## Feature: Shipment Creation ### Business Logic - Authenticated user creates a shipment with origin, destination, and package details - A unique tracking number is generated automatically - Shipment starts in "pending" status - A shipment event is recorded at creation ### Rules - Origin and destination cannot be identical - Package weight and dimensions are required - Tracking number must be human-readable and unique ### Edge Cases - Creating a shipment with an invalid address format - Concurrent creation requests from the same user
## Feature: Shipment Status Update ### Business Logic - System updates a shipment status as it moves through the logistics pipeline - Each update creates a new shipment event - Lifecycle: pending → picked_up → in_transit → out_for_delivery → delivered - Cancellation: pending or picked_up only ### Rules - Status cannot go backwards - Skipping a lifecycle step is not allowed - Delivered shipments cannot be updated further - Every status change must include a location ### Edge Cases - Attempting an invalid status transition - Updating an already delivered shipment - Cancelling from an ineligible status
We move faster without losing quality or control. Our value as a team is in the thinking, the architecture, and the decisions — not in writing boilerplate.