NIHAR MALALI

Instruction Driven Development sounds compelling in theory, but what does it look like in a real codebase? I built the task-tracker-copilot-md repository as a complete reference implementation — a production-style Task Management application using Angular 17+, Node.js/Express, and MongoDB, organized as a monorepo with layered instruction files at every level. Here are the patterns and lessons learned.

Repository Structure for IDD

The task-tracker monorepo is organized to maximize AI agent effectiveness while remaining maintainable for human developers.

• Root-Level Instruction Files — AGENTS.md provides Claude Code with the monorepo overview, workspace layout, and development workflows. .github/copilot-instructions.md provides Copilot with the tech stack, coding standards, and project-wide conventions.
• Shared Types Library — libs/shared/types contains TypeScript interfaces and Zod validation schemas shared between frontend and backend. Both Copilot and Claude Code reference these as the single source of truth for data shapes.
• Path-Scoped Instructions — .github/instructions/angular.instructions.md applies only to frontend code, enforcing standalone components, reactive forms, and OnPush change detection. .github/instructions/api.instructions.md applies to backend routes, enforcing Express middleware patterns and Zod validation.
• Prompt Templates — .github/prompts/new-endpoint.prompt.md and similar files encode repeatable workflows for common tasks. Invoking a prompt template gives the AI agent a step-by-step checklist customized for this specific project.
• Documentation as Specification — docs/ contains architecture decision records, API specifications, and component design documents that AI agents use as reference material when generating code.

Instruction File Design Lessons

• Be Specific, Not Verbose — “Use Zod schemas from libs/shared/types for all request validation” is better than a paragraph explaining why validation matters. AI agents need actionable rules, not justifications.
• Show, Don’t Just Tell — Include short code snippets in instruction files that demonstrate the expected pattern. A three-line example of a properly structured service method is worth more than a paragraph of description.
• Layer from General to Specific — Global instructions handle universal rules (naming conventions, import ordering). Scoped instructions handle technology-specific patterns (Angular signals, Express middleware). Prompts handle task-specific workflows.
• Include Anti-Patterns — Every instruction file has a “Do Not” section. Listing forbidden patterns (“never use any decorators” in Angular standalone context, “never import from relative paths across packages”) is often more impactful than positive guidance.
• Version with Code — Instruction files change in the same pull requests as the code they describe. When a migration from NgModules to standalone components happens, the instruction file updates in the same commit.

Monorepo-Specific Patterns

• Package Boundary Documentation — Instruction files explicitly define what each package exports and how other packages should import from it. This prevents AI agents from creating circular dependencies or reaching into internal modules.
• Shared Schema Strategy — The shared types library is referenced in every scoped instruction file, ensuring both Copilot and Claude Code use the canonical type definitions rather than creating local duplicates.
• Test Organization — Each package has its own test configuration documented in its scoped instruction file. Unit tests co-locate with source files, integration tests live in a dedicated directory, and end-to-end tests have their own workspace.

Results and Observations

Working with the task-tracker repository, both Copilot and Claude Code generate code that is remarkably consistent with human-written code in the same project. The AI agents follow the established patterns for error handling, validation, file organization, and testing without being reminded. The instruction files serve double duty as onboarding documentation for human developers joining the project.

The most valuable insight is that IDD is not extra work — it is documentation work that teams should be doing anyway, structured in a way that AI agents can consume. The marginal cost of making documentation “IDD-ready” is minimal compared to the productivity gains from AI agents that understand your codebase.

The task-tracker-copilot-md repository is open source and available as a starting point for teams adopting IDD. Fork it, adapt the instruction files to your stack, and experience the difference that structured AI context makes in your development workflow.