Instructions - Layer 2: Agent Primitives¶

Documentation views — these pages describe the instructions for the website. The normative, auto-applied sources live in instructions/. If a page and its source ever diverge, the source wins.

Markdown Prompt Engineering implemented as modular .instructions.md files with Context Engineering via applyTo patterns. These files customize GitHub Copilot's behavior for AL development in Business Central.

📋 What Are Instructions?¶

Instructions are auto-applied coding guidelines that: - Load automatically based on applyTo patterns (e.g., **/*.al) - Provide persistent context to GitHub Copilot during code generation - Implement best practices through structured markdown rules - Use semantic markdown (headers, lists, examples) for AI reasoning

🎯 How to Use Instructions¶

Instructions work automatically - no activation needed. When you: - Open an AL file → Instructions with matching applyTo patterns load - Type code → Copilot applies these guidelines in real-time - Ask for help → Context from relevant instructions is available

📦 Available Instructions (9 files)¶

Always Active (apply to `**/*.al`)¶

File	Purpose	Key Rules
al-guidelines.instructions.md	Master hub and integration guide	References all other instructions, AL development philosophy
al-code-style.instructions.md	Code formatting & organization	Feature-based structure, PascalCase, 120 char lines
al-naming-conventions.instructions.md	Naming standards	PascalCase for all, 26-char table limits, Codeunit suffixes
al-performance.instructions.md	Performance optimization	SetLoadFields, early filtering, temporary tables

Context-Triggered (specific patterns)¶

File	Apply Pattern	Purpose
al-error-handling.instructions.md	`*/.al`	TryFunctions, error labels, telemetry patterns
al-events.instructions.md	`*/.al`	Event publishers/subscribers, IntegrationEvent patterns
al-testing.instructions.md	`*/.al`, `/test/`	AL-Go test structure, test codeunits, scenarios

Integration & Reference¶

File	Purpose
copilot-instructions.md	Master integration guide for GitHub Copilot with all primitives
complete-development-flow.instructions.md	Visual workflow guide with Mermaid diagrams

🏗️ Architecture Patterns¶

Layer 1: Markdown Prompt Engineering¶

Each instruction uses structured markdown:

## Rule: Clear Title

### Intent
What this rule accomplishes

### Implementation  
How to implement it

### Examples
✅ Good / ❌ Bad examples

Layer 3: Context Engineering¶

Instructions use applyTo patterns for modular loading:

---
description: 'Performance optimization patterns'
applyTo: ['**/*.al']
---

💡 Best Practices¶

When Instructions Apply¶

✅ Active Coding - Instructions load during development
✅ Code Review - Context available for analysis
✅ Refactoring - Guidelines inform improvements
⚠️ Read-Only - May not apply when just viewing

Combining with Other Primitives¶

Instructions work alongside: - Agentic Workflows (@workspace use [prompt]) - For specific tasks - Agents (Use [mode-name]) - For strategic consultation - Both can reference instruction rules in their guidance

Creating Custom Instructions¶

Create file in this directory: al-[feature].instructions.md

Add frontmatter:

---
description: 'Brief description'
applyTo: ['**/*.al']  # Or more specific pattern
---

Structure content using semantic markdown
Update collection manifest in collections/al-development.collection.yml
Test by opening matching files and observing Copilot behavior

Collection Manifest: collections/al-development.collection.yml
Framework Reference: docs/framework/ai-native-instructions-architecture.md
User Guide: al-development.md
Contributing: CONTRIBUTING.md

📊 Validation¶

Run npm run validate to verify: - All instruction files exist - Frontmatter is properly formatted - File naming conventions are followed - applyTo patterns are valid

Framework Compliance: These instructions implement AI Native-Instructions Architecture - Layer 2 (Agent Primitives) using Layer 1 (Markdown Prompt Engineering) and Layer 3 (Context Engineering) principles.

Version: 2.8.0 Total Instructions: 9 Last Updated: 2025-11-25