AI-Ready Documentation Structure for Laravel Microservices: From Basic to Advanced Guide

Uncategorized
Posted on | by rajeshkumar

Introduction

When you want to move software delivery from a human-led process to an AI-assisted process using Claude, Codex, or any AI coding agent, the biggest mistake is to start directly with code.

AI coding does not fail only because the AI writes bad code. It usually fails because the AI does not have enough reliable context.

For a running production application with multiple Laravel services, documentation becomes the operating system for AI. It tells Claude how to think, tells Codex where to make changes, and tells humans how to review the output safely.

This guide explains what markdown files should exist at the root level, application level, service level, and feature level before starting serious AI-assisted development.

The goal is simple:

Give AI enough context to work safely, while keeping the context small enough to save tokens and avoid confusion.

1. Why Documentation Matters Before AI Coding

In traditional software development, senior engineers carry a lot of system knowledge in their heads.

They know:

  • Which service owns which data
  • Which API calls which service
  • Which database table should not be touched
  • Which queue job is critical
  • Which environment variable is dangerous
  • Which old code is fragile
  • Which migration can break production

AI does not know any of this automatically.

If you give Codex a vague instruction such as:

Upgrade booking flow and fix notification issue.

It may inspect the repository and make a reasonable guess, but in a microservice system, a reasonable guess can still be wrong.

For example, it may:

  • Modify the wrong service
  • Duplicate business logic
  • Add cross-service database access
  • Break an API contract
  • Log sensitive tokens
  • Change booking lifecycle rules without approval
  • Update frontend code while ignoring backend API compatibility

That is why markdown documentation is not optional. It is the control layer for AI-assisted development.

2. Documentation Principles for AI Coding

Before creating files, follow these principles.

2.1 Keep documentation layered

Do not put everything into one giant file.

Use layers:

  1. Root-level documentation
  2. App/workspace-level documentation
  3. Service-level documentation
  4. Feature-level documentation
  5. AI-agent documentation
  6. Template documentation

This helps Claude and Codex read only what they need.

2.2 Keep documents small and focused

A 3,000-line architecture file is hard for humans and AI.

Better structure:

ARCHITECTURE.md
SERVICE-BOUNDARIES.md
API-CONTRACTS.md
DATABASE-DESIGN.md
QUEUE-DESIGN.md
SECURITY-CHECKLIST.md
TEST-STRATEGY.md

Each file has one responsibility.

2.3 Prefer stable context over temporary detail

Stable context belongs in root and service documentation.

Examples:

  • Service ownership
  • Tech stack
  • Coding standards
  • Authentication model
  • Security rules
  • Database ownership

Temporary context belongs in feature folders.

Examples:

  • A specific requirement
  • A specific bug fix
  • A specific release plan
  • A specific migration task

2.4 Avoid token waste

AI token waste happens when you repeatedly paste huge context into every prompt.

Instead, keep documents in the repository and ask AI to read the relevant files.

Bad approach:

Here is my full architecture, all service docs, all APIs, and all database tables. Now fix one button.

Better approach:

Read ARCHITECTURE.md, SERVICE-BOUNDARIES.md, and docs/services/bookings-new.md. Then inspect only the booking approval flow and propose a fix.

3. Recommended Root Folder Structure

At the root of your workspace, create this structure:

/
  README.md
  ARCHITECTURE.md
  SERVICE-BOUNDARIES.md
  TECH-STACK.md
  AI-WORKFLOW.md
  AGENTS.md
  CLAUDE.md
  CODEX.md
  CONTRIBUTING.md
  SECURITY.md

/docs
  API-CONTRACTS.md
  DATABASE-DESIGN.md
  QUEUE-DESIGN.md
  TEST-STRATEGY.md
  RELEASE-ROLLBACK-PLAN.md
  MIGRATION-PLAN.md
  LARAVEL-11-TO-13-UPGRADE.md
  VUE-2-TO-3-UPGRADE.md
  BOOTSTRAP-DECISION.md

/docs/services
  professnow-new.md
  professional-new.md
  bookings-new.md
  category-new.md
  customer-managers-new.md
  notification-new.md
  admin-new.md
  gallery.md

/docs/templates
  REQUIREMENT-TEMPLATE.md
  PLAN-TEMPLATE.md
  HLD-TEMPLATE.md
  LLD-TEMPLATE.md
  CODEX-TASK-TEMPLATE.md
  TEST-PLAN-TEMPLATE.md
  SECURITY-REVIEW-TEMPLATE.md
  RELEASE-PLAN-TEMPLATE.md
  ROLLBACK-PLAN-TEMPLATE.md

/docs/features
  FEATURE-001-example/
    REQUIREMENT.md
    PLAN.md
    HLD.md
    LLD.md
    CODEX-TASKS.md
    TEST-PLAN.md
    SECURITY-REVIEW.md
    RELEASE-PLAN.md
    ROLLBACK-PLAN.md

This may look like a lot, but not every file needs to be huge. Many of them can start with one or two pages.

4. Root-Level Files

Root-level files define the full workspace and AI behavior.

These are the most important files before starting AI-assisted coding.

4.1 README.md

Purpose

This is the entry point for humans and AI.

It should explain:

  • What the project is
  • How the workspace is structured
  • How to install dependencies
  • How to run services locally
  • How to run tests
  • Where deeper documentation lives

Why it should be there

AI agents often start by reading README.md. If this file is missing or outdated, AI may misunderstand the project immediately.

Minimal content

# Project Name

## Overview

This workspace contains multiple Laravel services and one standalone gallery application.

## Services

- professnow-new
- professional-new
- bookings-new
- category-new
- customer-managers-new
- notification-new
- admin-new
- gallery

## Tech Stack

- PHP 8.2
- Laravel 11 currently
- Laravel 13 target
- MariaDB 10.4.32
- REST APIs
- Laravel Passport
- Blade
- Vue
- Bootstrap

## Documentation

Start with:

- ARCHITECTURE.md
- SERVICE-BOUNDARIES.md
- TECH-STACK.md
- AI-WORKFLOW.md
- CODEX.md
- CLAUDE.md

4.2 ARCHITECTURE.md

Purpose

This file explains the system architecture.

It should include:

  • Service list
  • Service responsibilities
  • Main data flows
  • API communication model
  • Authentication model
  • Queue model
  • Known risks
  • Deployment overview

Why it should be there

This is the most important file for Claude and Codex.

Without it, AI may treat the system as one Laravel monolith instead of multiple services.

Best practice

Keep this file high-level. Do not put every endpoint or table in it.

Use separate files for API and database details.

4.3 SERVICE-BOUNDARIES.md

Purpose

This file defines what each service owns and what it must not own.

Why it should be there

Service-boundary mistakes are among the biggest AI coding risks in microservice systems.

For example:

  • Booking lifecycle logic should stay in the booking service
  • Notification delivery should stay in the notification service
  • Category catalog ownership should stay in the category service
  • Admin service should aggregate, not duplicate domain writes

Minimal content

# Service Boundaries

## professnow-new

Owns customer/user web and mobile behavior.

Must not own:

- Booking lifecycle state
- Professional profile data
- Notification delivery internals

## bookings-new

Owns booking rows and booking lifecycle.

Must not own:

- Customer profile data
- Professional profile media
- Notification templates

Token-saving benefit

Instead of pasting full architecture every time, you can tell Codex:

Before coding, read SERVICE-BOUNDARIES.md and do not change ownership rules.

4.4 TECH-STACK.md

Purpose

This file defines current and target technology versions.

Your current baseline

Language: PHP 8.2.12
Current framework: Laravel 11
Target framework: Laravel 13
Database: MariaDB 10.4.32
Queue: MariaDB / Laravel database queue
APIs: REST
Template engine: Blade
Current CSS: Bootstrap 5.3.8
Proposed CSS: Bootstrap ^4.1.0
Current JavaScript: Vue.js 2
Proposed JavaScript: Vue.js 3

Why it should be there

AI frequently assumes modern defaults. This file prevents wrong assumptions.

Important best practice

The proposed Bootstrap version should be reviewed carefully because Bootstrap 5.3.8 to Bootstrap 4.1.0 looks like a downgrade.

Document the decision clearly:

# Bootstrap Decision

Current Bootstrap version is 5.3.8.
Proposed version is ^4.1.0.

This is a downgrade and must not be done unless there is a specific compatibility reason.

4.5 AI-WORKFLOW.md

Purpose

This file defines how humans, Claude, Codex, and CI/CD should work together.

Why it should be there

AI needs process boundaries, not only code boundaries.

Recommended flow

Requirement
  -> Claude analysis
  -> Plan
  -> HLD
  -> Human approval
  -> LLD
  -> Codex tasks
  -> Codex implementation
  -> Tests
  -> Security scan
  -> Claude review
  -> Human review
  -> Merge
  -> Release

Minimal content

# AI Workflow

## Claude Responsibilities

- Requirement analysis
- Architecture planning
- HLD
- LLD
- Security review
- PR review
- Documentation

## Codex Responsibilities

- Code implementation
- Test generation
- Refactoring
- Small fixes
- PR preparation

## Human Responsibilities

- Product decision
- Architecture approval
- Security approval
- Code review
- Production release approval

4.6 AGENTS.md

Purpose

This file gives common rules for all AI agents.

Claude, Codex, and other coding agents can use this as their shared rulebook.

Why it should be there

If multiple AI tools are used, each tool should follow the same project rules.

Recommended content

# AI Agent Rules

## Always Do

- Read ARCHITECTURE.md before large changes.
- Read SERVICE-BOUNDARIES.md before modifying service logic.
- Read the relevant service document before editing code.
- Create a plan before code changes.
- Add or update tests for every behavior change.
- Keep changes small and reviewable.

## Never Do

- Do not log tokens, secrets, OAuth credentials, or PII.
- Do not create cross-service database access.
- Do not change service ownership without approval.
- Do not modify unrelated services.
- Do not perform large framework upgrades together with feature changes.
- Do not remove tests to make builds pass.

4.7 CLAUDE.md

Purpose

This file defines how Claude should behave.

Claude is best used for:

  • Analysis
  • Architecture
  • HLD
  • LLD
  • Review
  • Risk detection
  • Security reasoning
  • Documentation

Why it should be there

Claude should not just answer casually. It should follow your software delivery process.

Recommended content

# Claude Guide

## Role

Claude acts as analyst, architect, reviewer, and documentation assistant.

## Required Output for Feature Requests

1. Requirement summary
2. Affected services
3. Current flow
4. Proposed flow
5. Architecture impact
6. HLD
7. LLD
8. API impact
9. Database impact
10. Security impact
11. Codex tasks
12. Test plan
13. Release and rollback plan

## Review Rules

Claude must check:

- Service ownership
- API compatibility
- Database safety
- Security risk
- Test coverage
- Rollback safety

4.8 CODEX.md

Purpose

This file tells Codex how to safely modify the repository.

Why it should be there

Codex is more implementation-focused. It needs strict coding boundaries.

Recommended content

# Codex Guide

## Before Coding

1. Read the assigned task.
2. Read ARCHITECTURE.md if the task affects multiple services.
3. Read SERVICE-BOUNDARIES.md.
4. Read the relevant service document.
5. Inspect existing code before creating new code.
6. Produce a short implementation plan.

## While Coding

- Keep changes small.
- Follow existing Laravel conventions.
- Add validation for new inputs.
- Add tests for changed behavior.
- Do not change unrelated files.
- Do not hardcode secrets.
- Do not log tokens or sensitive data.

## After Coding

Run relevant commands:

```bash
composer test
php artisan test
php artisan route:list
php artisan migrate --pretend

Update documentation if behavior changes.


---

## 4.9 `CONTRIBUTING.md`

### Purpose

This file defines how humans and AI should contribute code.

It should include:

- Branch naming
- Commit format
- PR checklist
- Review process
- Test requirements
- Documentation requirements

### Why it should be there

AI-generated code still needs a contribution process.

### Minimal PR checklist

```markdown
# PR Checklist

- [ ] Requirement is linked
- [ ] Affected services are listed
- [ ] Service ownership is respected
- [ ] Tests are added or updated
- [ ] API changes are documented
- [ ] Database migrations are safe
- [ ] Security risks are reviewed
- [ ] Rollback plan is documented

4.10 SECURITY.md

Purpose

This file defines security rules for the full workspace.

Why it should be there

AI must know which actions are dangerous.

Recommended content

# Security Rules

## Never Commit

- Access tokens
- Client secrets
- API keys
- FCM keys
- Twilio credentials
- Database passwords
- OAuth secrets
- Private certificates

## Never Log

- Bearer tokens
- Client secrets
- Passwords
- OTPs
- Personal data unless explicitly required and masked

## Required Checks

- Request validation
- Authorization checks
- Mass assignment protection
- File upload validation
- Rate limiting for sensitive endpoints
- Secure error handling
- Secret scanning

5. /docs Folder Files

The /docs folder contains deeper system documentation.

Root files tell AI where to start. /docs files tell AI how specific parts work.

5.1 docs/API-CONTRACTS.md

Purpose

Defines REST API contracts between services.

Why it should be there

Microservices communicate through APIs. Breaking an API can break another service.

Include

  • Endpoint path
  • HTTP method
  • Owning service
  • Calling service
  • Auth type
  • Request payload
  • Response payload
  • Error responses
  • Backward compatibility notes

Minimal format

# API Contracts

## bookings-new: Create Booking

Method: POST
Path: /bookings/storeBookings
Auth: Passport bearer token
Called by: professnow-new

### Request

```json
{
  "professional_id": 123,
  "customer_id": 456,
  "booking_date": "2026-04-25"
}

Response

{
  "success": true,
  "booking_id": 999
}


---

## 5.2 `docs/DATABASE-DESIGN.md`

### Purpose

Defines database ownership and table responsibility.

### Why it should be there

AI should not create or modify tables in the wrong service.

### Include

```markdown
# Database Design

## Rules

- Each service owns its own tables.
- Do not create cross-service joins.
- Do not directly query another service database.
- Use APIs for cross-service communication.

## bookings-new

Owns:

- bookings
- booking lifecycle flags
- rating/review records

## professional-new

Owns:

- profiles
- documents
- image galleries
- video galleries
- professional availability

5.3 docs/QUEUE-DESIGN.md

Purpose

Defines async behavior and queue usage.

Why it should be there

Your system uses Laravel queues, but queue behavior depends on runtime configuration.

AI should not assume jobs are truly asynchronous unless queue workers are configured.

Include

  • Queue driver
  • Jobs by service
  • Retry rules
  • Failed job handling
  • Worker deployment
  • Idempotency rules

Minimal content

# Queue Design

## Current Default

Laravel queue may default to sync unless QUEUE_CONNECTION is configured.

## Rules

- Use jobs for slow notification work.
- Define retry behavior.
- Make jobs idempotent where possible.
- Do not make user-facing requests wait for slow email, WhatsApp, or push work.

5.4 docs/TEST-STRATEGY.md

Purpose

Defines required testing standards.

Why it should be there

AI often writes code faster than it writes good tests. This file forces test discipline.

Include

# Test Strategy

## Required Test Types

- Unit tests
- Feature tests
- API tests
- Integration tests
- Contract tests
- Queue/job tests
- Migration tests
- Security negative tests

## Rule

Every behavior change must include tests or a documented reason why tests were not added.

5.5 docs/RELEASE-ROLLBACK-PLAN.md

Purpose

Defines how releases and rollbacks should happen.

Why it should be there

AI may generate migrations or framework upgrades without thinking through rollback.

Include

  • Deployment order
  • Migration order
  • Rollback commands
  • Feature flags
  • Data backup
  • Smoke tests
  • Monitoring checks

5.6 docs/MIGRATION-PLAN.md

Purpose

Defines the overall migration strategy.

For your case, it should cover:

  • Laravel 11 to Laravel 13
  • Vue 2 to Vue 3
  • Bootstrap decision
  • Queue improvement
  • Security hardening
  • API contract cleanup
  • Test coverage improvement

Why it should be there

AI should not mix all migrations into one large risky PR.

Best practice

Use phased migration:

Phase 1: Documentation and tests
Phase 2: Security cleanup
Phase 3: Service-by-service Laravel upgrade
Phase 4: Vue migration
Phase 5: Frontend CSS decision
Phase 6: Queue and async improvements
Phase 7: CI/CD hardening

5.7 docs/LARAVEL-11-TO-13-UPGRADE.md

Purpose

Specific upgrade plan for Laravel.

Include

  • Composer dependency review
  • PHP compatibility
  • Laravel breaking changes
  • Package compatibility
  • Config changes
  • Middleware changes
  • Auth/Passport compatibility
  • Test commands
  • Rollback plan

Why it should be there

Framework upgrades are high risk. Codex should not perform them casually.

5.8 docs/VUE-2-TO-3-UPGRADE.md

Purpose

Specific frontend migration guide.

Include

  • Vue 2 component inventory
  • Vue 3 compatibility issues
  • Build tooling changes
  • Plugin compatibility
  • Component migration order
  • Regression test strategy

Why it should be there

Vue migration should not be mixed with Laravel migration unless absolutely required.

5.9 docs/BOOTSTRAP-DECISION.md

Purpose

Clarifies Bootstrap direction.

Why it should be there

Your current Bootstrap version is 5.3.8 and proposed version is ^4.1.0. That appears to be a downgrade.

Document why:

  • Is Bootstrap 4 required by legacy templates?
  • Is BootstrapVue dependency forcing it?
  • Is 4.1.0 a mistake?
  • Should the target remain Bootstrap 5?
  • Should another Vue 3 UI library be used?

Best practice

Do not allow AI to downgrade Bootstrap without explicit approval.

6. Service-Level Documentation

Each service should have its own markdown file under:

/docs/services

Example:

/docs/services/bookings-new.md
/docs/services/notification-new.md
/docs/services/professional-new.md

This keeps context small.

Instead of giving Codex the entire architecture, you can say:

Read ARCHITECTURE.md, SERVICE-BOUNDARIES.md, and docs/services/bookings-new.md. Then fix booking approval issue.

6.1 Service document template

Each service file should follow this format:

# Service: service-name

## Responsibility

## What This Service Owns

## What This Service Must Not Own

## Main Routes / APIs

## Database Tables Owned

## Queue Jobs

## External Calls

## Incoming Calls From Other Services

## Authentication

## Important Files

## Known Risks

## Test Commands

## Deployment Notes

## AI Coding Rules for This Service

6.2 Example: docs/services/bookings-new.md

# Service: bookings-new

## Responsibility

Owns booking and appointment lifecycle.

## Owns

- Booking creation
- Booking approval
- Booking cancellation
- Booking completion
- Booking reviews and ratings
- Booking calendar views
- Auto-cancel behavior

## Must Not Own

- Customer profile data
- Professional profile media
- Notification templates
- Profession category catalog

## Main APIs

- /bookings
- Booking creation endpoints
- Approval endpoints
- Cancellation endpoints
- Rating endpoints

## Database Tables

- bookings

## External Calls

- notification-new for booking notifications
- professional-new for rating aggregate update

## Known Risks

- Booking lifecycle changes are high risk.
- Notification calls may be synchronous.
- Auto-cancel scheduler command must be verified.

## AI Coding Rules

- Do not move booking lifecycle logic to another service.
- Do not send email/WhatsApp directly from this service unless already existing behavior requires it.
- Use notification-new for notification delivery.
- Add tests for every lifecycle state change.

6.3 Example: docs/services/notification-new.md

# Service: notification-new

## Responsibility

Owns notification delivery integrations and notification jobs.

## Owns

- Email notifications
- WhatsApp notifications
- Push notifications
- Notification jobs
- Notification templates

## Must Not Own

- Booking lifecycle state
- Customer profile ownership
- Professional profile ownership

## External Integrations

- Laravel Mail
- Twilio WhatsApp
- Firebase Cloud Messaging

## Known Risks

- Secrets must not be hardcoded.
- Tokens and keys must not be logged.
- Slow notification work should be queued.

## AI Coding Rules

- Move hardcoded secrets to environment-backed config.
- Add retry and failed job handling where appropriate.
- Do not expose notification payloads containing sensitive data.

7. Feature-Level Documentation

Every coding task should have its own feature folder.

Example:

/docs/features/FEATURE-002-fix-booking-auto-cancel/
  REQUIREMENT.md
  PLAN.md
  HLD.md
  LLD.md
  CODEX-TASKS.md
  TEST-PLAN.md
  SECURITY-REVIEW.md
  RELEASE-PLAN.md
  ROLLBACK-PLAN.md

This is extremely useful for AI because each feature has its own compact context.

7.1 REQUIREMENT.md

Purpose

Defines what needs to be built or fixed.

Include

# Requirement

## Problem

## Business Goal

## Current Behavior

## Expected Behavior

## Affected Users

## Acceptance Criteria

## Out of Scope

Why it should be there

AI needs the requirement separated from implementation details.

7.2 PLAN.md

Purpose

Defines the execution plan.

Include

# Plan

## Summary

## Affected Services

## Steps

## Dependencies

## Risks

## Human Approval Needed

Why it should be there

This prevents Codex from jumping straight into code.

7.3 HLD.md

Purpose

High-level design.

Include

  • Objective
  • Current flow
  • Proposed flow
  • Affected services
  • Data flow
  • API flow
  • Security impact
  • Failure scenarios
  • Rollback approach

Why it should be there

Claude should prepare this before Codex implementation for non-trivial features.

7.4 LLD.md

Purpose

Low-level implementation design.

Include

  • Files to change
  • Controllers
  • Services
  • Models
  • Requests
  • Jobs
  • Migrations
  • Configs
  • Error handling
  • Logging
  • Test impact

Why it should be there

Codex performs much better when LLD is precise.

7.5 CODEX-TASKS.md

Purpose

Turns the approved design into implementation instructions for Codex.

Include

# Codex Tasks

## Task 1: Inspect Existing Flow

## Task 2: Update Validation

## Task 3: Modify Controller Logic

## Task 4: Add Tests

## Task 5: Run Commands

## Acceptance Criteria

## Do Not Change

Why it should be there

Codex needs narrow, executable tasks.

Do not give Codex broad goals like:

Improve booking system.

Give it precise tasks:

In bookings-new, inspect BookingController and update approval validation to reject invalid state transitions. Add feature tests for pending-to-approved, canceled-to-approved rejection, and completed-to-canceled rejection.

7.6 TEST-PLAN.md

Purpose

Defines required tests before coding starts.

Include

# Test Plan

| Test Type | Service | Scenario | Expected Result |
| --- | --- | --- | --- |
| Feature | bookings-new | Approve pending booking | Booking becomes approved |
| Negative | bookings-new | Approve canceled booking | Request is rejected |
| Integration | bookings-new + notification-new | Booking approval sends notification | Notification request is made |

7.7 SECURITY-REVIEW.md

Purpose

Defines security impact.

Include

  • Auth impact
  • Authorization impact
  • PII handling
  • Token handling
  • File upload risks
  • Input validation
  • Logging risks
  • Rate limiting
  • Audit needs

7.8 RELEASE-PLAN.md

Purpose

Defines deployment steps.

Include

  • Services to deploy
  • Deployment order
  • Migration order
  • Cache/config clear commands
  • Queue restart commands
  • Smoke tests
  • Monitoring checks

7.9 ROLLBACK-PLAN.md

Purpose

Defines how to safely revert.

Include

  • Code rollback
  • Migration rollback
  • Data rollback
  • Config rollback
  • Feature flag rollback
  • Manual verification

8. Minimal Setup: Start Small

You do not need to create every file perfectly on day one.

Start with this minimal setup.

/
  README.md
  ARCHITECTURE.md
  SERVICE-BOUNDARIES.md
  TECH-STACK.md
  AGENTS.md
  CLAUDE.md
  CODEX.md
  SECURITY.md

/docs
  TEST-STRATEGY.md
  MIGRATION-PLAN.md

/docs/services
  bookings-new.md
  notification-new.md
  professional-new.md

Why these first?

Because they protect the highest-risk areas:

  • Architecture misunderstanding
  • Service-boundary mistakes
  • Unsafe AI code changes
  • Missing security controls
  • Missing tests

Then add feature folders as needed.

9. Advanced Setup: Mature AI Delivery System

Once the minimal setup works, move to an advanced setup.

Add:

/docs
  API-CONTRACTS.md
  DATABASE-DESIGN.md
  QUEUE-DESIGN.md
  RELEASE-ROLLBACK-PLAN.md
  LARAVEL-11-TO-13-UPGRADE.md
  VUE-2-TO-3-UPGRADE.md
  BOOTSTRAP-DECISION.md

/docs/templates
  REQUIREMENT-TEMPLATE.md
  PLAN-TEMPLATE.md
  HLD-TEMPLATE.md
  LLD-TEMPLATE.md
  CODEX-TASK-TEMPLATE.md
  TEST-PLAN-TEMPLATE.md
  SECURITY-REVIEW-TEMPLATE.md

This creates a repeatable AI SDLC.

For every new feature:

  1. Create requirement
  2. Ask Claude for plan
  3. Ask Claude for HLD
  4. Human approves
  5. Ask Claude for LLD
  6. Generate Codex tasks
  7. Codex implements
  8. Tests run
  9. Claude reviews
  10. Human approves
  11. Release

10. Token-Saving Best Practices While Coding

Token saving is not only about cost. It also improves AI accuracy.

The more irrelevant context you provide, the more likely AI is to get distracted.

10.1 Do not paste the full repository

Avoid this:

Here is the entire project. Fix this issue.

Better:

Read only:
- ARCHITECTURE.md
- SERVICE-BOUNDARIES.md
- docs/services/bookings-new.md
- app/Http/Controllers/Api/Booking/BookingController.php

Then propose a fix.

10.2 Use feature folders as compact context

Instead of repeating the same explanation, create:

/docs/features/FEATURE-123/REQUIREMENT.md
/docs/features/FEATURE-123/PLAN.md
/docs/features/FEATURE-123/LLD.md

Then prompt:

Use docs/features/FEATURE-123 as the source of truth. Implement only Task 1 from CODEX-TASKS.md.

10.3 Give AI a file budget

This is very effective with Codex.

Example:

Inspect at most 8 files before proposing a plan. Do not edit code yet.

Or:

Only modify files listed in LLD.md unless you explain why another file is required.

10.4 Separate analysis from implementation

Do not ask AI to analyze and code in one giant step.

Use two steps:

Step 1:

Analyze the issue and produce a plan. Do not edit files.

Step 2:

Implement the approved plan. Modify only listed files. Add tests.

This saves tokens because mistakes are caught before implementation.

10.5 Use service-specific docs

For a booking issue, do not load every service document.

Use:

ARCHITECTURE.md
SERVICE-BOUNDARIES.md
docs/services/bookings-new.md

Add notification-new.md only if notifications are affected.

10.6 Use summaries for large files

If a file is huge, create a summary file.

Example:

docs/services/bookings-new-code-map.md

Include:

  • Important controllers
  • Important models
  • Important routes
  • Important jobs
  • Known risks

Then AI can read the summary first and inspect code only when necessary.

10.7 Use templates instead of repeating instructions

Do not paste the HLD format every time.

Keep:

docs/templates/HLD-TEMPLATE.md

Then prompt:

Create HLD using docs/templates/HLD-TEMPLATE.md.

10.8 Keep prompts narrow

Bad prompt:

Upgrade Laravel, Vue, Bootstrap, fix booking, improve security, and clean code.

Good prompt:

For bookings-new only, analyze Laravel 11 to Laravel 13 upgrade blockers. Do not modify code. Create docs/features/FEATURE-laravel-upgrade-bookings/PLAN.md.

10.9 Use checkpoints

For risky changes, stop AI at checkpoints.

Example:

Stop after creating the plan. Wait for approval before editing files.

Then:

Implement only Step 1 and Step 2 from the approved plan.

10.10 Avoid repeated architecture explanations

Once the files exist, stop explaining the architecture in every prompt.

Use:

Follow ARCHITECTURE.md and SERVICE-BOUNDARIES.md.

This saves tokens and keeps instructions consistent.

11. Best Practices for Claude

Use Claude mostly for thinking work.

Good Claude tasks:

  • Analyze architecture
  • Create HLD
  • Create LLD
  • Identify risks
  • Review PRs
  • Generate test strategy
  • Review security issues
  • Create migration plans

Claude prompt example:

Read ARCHITECTURE.md, SERVICE-BOUNDARIES.md, TECH-STACK.md, and docs/services/bookings-new.md.

Create HLD and LLD for improving booking approval validation.

Do not write code.

Include affected services, API impact, database impact, security impact, test plan, and rollback plan.

12. Best Practices for Codex

Use Codex mostly for implementation.

Good Codex tasks:

  • Implement approved LLD
  • Add tests
  • Refactor small modules
  • Fix bugs
  • Update validation
  • Update migrations
  • Update docs after code change

Codex prompt example:

Use docs/features/FEATURE-123/CODEX-TASKS.md.

Implement Task 2 only.

Constraints:
- Modify only bookings-new.
- Do not change API response format.
- Do not change database schema.
- Add feature tests.
- Run php artisan test for the affected service.

13. Human Approval Gates

Even with AI, humans should approve high-risk changes.

Require approval for:

  • Database migrations
  • Authentication changes
  • Authorization changes
  • Booking lifecycle changes
  • Notification delivery changes
  • Framework upgrades
  • Vue major version migration
  • Queue driver changes
  • Production deployment
  • Security-sensitive code
  • Cross-service API contract changes

This should be written in AI-WORKFLOW.md, AGENTS.md, and CONTRIBUTING.md.

14. Recommended Coding Workflow

Use this workflow for every coding task.

1. Create feature folder.
2. Write REQUIREMENT.md.
3. Ask Claude to create PLAN.md.
4. Ask Claude to create HLD.md if architecture is affected.
5. Ask Claude to create LLD.md.
6. Human reviews and approves.
7. Generate CODEX-TASKS.md.
8. Codex implements one task at a time.
9. Codex adds tests.
10. CI/CD runs checks.
11. Claude reviews the diff.
12. Human approves merge.
13. Release using RELEASE-PLAN.md.
14. Roll back using ROLLBACK-PLAN.md if required.

15. What to Create First for Your Project

For your specific Laravel microservice project, start in this order.

Step 1: Root files

README.md
ARCHITECTURE.md
SERVICE-BOUNDARIES.md
TECH-STACK.md
AGENTS.md
CLAUDE.md
CODEX.md
SECURITY.md

Step 2: Core docs

docs/TEST-STRATEGY.md
docs/MIGRATION-PLAN.md
docs/API-CONTRACTS.md
docs/DATABASE-DESIGN.md
docs/QUEUE-DESIGN.md

Step 3: Service docs

docs/services/professnow-new.md
docs/services/professional-new.md
docs/services/bookings-new.md
docs/services/category-new.md
docs/services/customer-managers-new.md
docs/services/notification-new.md
docs/services/admin-new.md
docs/services/gallery.md

Step 4: Migration-specific docs

docs/LARAVEL-11-TO-13-UPGRADE.md
docs/VUE-2-TO-3-UPGRADE.md
docs/BOOTSTRAP-DECISION.md

Step 5: Templates

docs/templates/REQUIREMENT-TEMPLATE.md
docs/templates/PLAN-TEMPLATE.md
docs/templates/HLD-TEMPLATE.md
docs/templates/LLD-TEMPLATE.md
docs/templates/CODEX-TASK-TEMPLATE.md
docs/templates/TEST-PLAN-TEMPLATE.md
docs/templates/SECURITY-REVIEW-TEMPLATE.md
docs/templates/RELEASE-PLAN-TEMPLATE.md
docs/templates/ROLLBACK-PLAN-TEMPLATE.md

16. Final Recommended Minimum

If you want the shortest practical setup before starting AI coding, create only these first:

README.md
ARCHITECTURE.md
SERVICE-BOUNDARIES.md
TECH-STACK.md
AGENTS.md
CLAUDE.md
CODEX.md
SECURITY.md
docs/TEST-STRATEGY.md
docs/MIGRATION-PLAN.md
docs/services/bookings-new.md
docs/services/notification-new.md
docs/services/professional-new.md

This gives AI enough structure to start safely without overwhelming the context window.

Conclusion

AI-assisted coding works best when the repository itself teaches the AI how the system works.

For a Laravel microservice system, the most important thing is not only documenting the code. It is documenting ownership, boundaries, contracts, risks, and approval gates.

Start small:

  • Root rules
  • Service boundaries
  • Tech stack
  • AI workflow
  • Service docs
  • Feature folders

Then mature gradually into:

  • API contracts
  • Database ownership
  • Queue design
  • Test strategy
  • Security checklists
  • Release and rollback plans
  • Codex task templates

The best AI coding setup is not where AI has unlimited freedom.

The best setup is where AI has enough context, clear boundaries, and human approval gates.

That is how you move from human-led delivery to AI-assisted software delivery safely.

Leave a Reply