Scoping Path-Specific Instructions

1. Using applyTo Glob Patterns

The applyTo property in AI-assisted development tools allows you to scope instructions to specific file paths using glob patterns. This ensures that AI suggestions or actions are only applied where intended.

Pattern	Description	Example
*.js	Matches all files with the `.js` extension	`applyTo: "*.js"`
src/*/.ts	Matches all `.ts` files in the `src` directory and subdirectories	`applyTo: "src/*/.ts"`
config/*.yaml	Matches all `.yaml` files in the `config` directory only	`applyTo: "config/*.yaml"`
/test/	Matches all files in any `test` directory	`applyTo: "/test/"`

Example: Applying AI instructions to JavaScript files only

{
  "applyTo": "*.js",
  "instruction": "Ensure all functions have JSDoc comments"
}

Example: Applying AI instructions to TypeScript files in a specific directory

{
  "applyTo": "src/**/*.ts",
  "instruction": "Refactor all classes to use modern ES6 syntax"
}

2. Creating .instructions.md Files

Example: Basic .instructions.md Structure

# AI Development Instructions

## Project Overview
This project uses React with TypeScript and Tailwind CSS for styling.

## Coding Standards
- Use camelCase for variables
- Prefer functional components over class components
- All UI elements must be responsive

## File Structure Guidelines
- Components go in /src/components/
- Utilities go in /src/utils/
- Styles go in /src/styles/

## AI Interaction Rules
- Never generate code that conflicts with existing project structure
- Always follow the project's linting rules (ESLint, Prettier)

Section	Description	Usage
Project Overview	High-level description of the project's purpose and technologies	Helps AI understand context before generating code
Coding Standards	Specific style guidelines and conventions to follow	Ensures consistency with existing codebase
File Structure Guidelines	Rules about where files should be placed	Prevents AI from creating files in wrong directories
AI Interaction Rules	Constraints on how AI can interact with the codebase	Maintains project integrity and prevents conflicts

Note: The .instructions.md file should be placed in the root of your project directory to ensure AI tools can easily locate and read it.

3. Scoping Instructions to File Types

File Type	Scoping Instruction	Notes
.js	`Focus on JavaScript syntax and patterns`	Include ES6+ features, common libraries like React or Node.js
.ts	`Focus on TypeScript type definitions and interfaces`	Highlight type safety, generics, and module systems
.html	`Focus on HTML structure and semantic elements`	Emphasize accessibility and modern layout techniques
.css	`Focus on CSS selectors, properties, and layout models`	Include Flexbox, Grid, and modern best practices
.json	`Focus on JSON schema validation and structure`	Highlight key-value pair organization and nesting
.md	`Focus on Markdown syntax and formatting rules`	Include headers, lists, code blocks, and links
.py	`Focus on Python syntax and standard library usage`	Highlight indentation, functions, and modules
.java	`Focus on Java class structure and object-oriented principles`	Include packages, inheritance, and exception handling

Example: JavaScript File Scoping

// Example of scoping to JavaScript files
const myFunction = () => {
  const localVar = "local";
  return localVar;
};

// This function is scoped to JS syntax and patterns
module.exports = { myFunction };

4. Scoping Instructions to Directories

Directory	Description	Scoping Behavior	Notes
src/	Source code directory	Applies to all files within	Default scope for most projects
tests/	Test files directory	Restricted to test-related instructions	May exclude from general AI scope
docs/	Documentation directory	Applies to documentation generation	Can use different instruction sets
config/	Configuration files directory	Applies to config file parsing	May require special handling for schema validation

Example: Directory Scoping Configuration

{
  "scoping": {
    "src/": {
      "instructions": "Generate code with strict adherence to style guide",
      "exclude": ["tests/"]
    },
    "docs/": {
      "instructions": "Generate documentation in markdown format",
      "include": ["README.md"]
    }
  }
}

Note: Scoping rules can be overridden per file or subdirectory using nested configurations.

Warning: Misconfigured directory scoping may lead to AI generating code in unintended locations.

5. Combining Path Patterns with Alternation

Pattern	Description	Usage
path/.*	Matches any path starting with `path/`	`path/.*`
src\/(main\|test)\/.*	Matches paths under `src/main/` or `src/test/`	`src\/(main\|test)\/.*`
.*\.(js\|ts)$	Matches files ending in `.js` or `.ts`	`.*\.(js\|ts)$`

Example: Combining Path Patterns with Alternation

const patterns = [
  "src\/(main|test)\/.*",
  ".*\.(js|ts)$"
];

const combinedPattern = patterns.join("|");
console.log(combinedPattern); // src\/(main|test)\/.*|.*\.(js|ts)$

Note: Use | to combine multiple path patterns in alternation.

6. Setting Instruction Priority Order

Instruction	Priority Level	Description
core.task.focus	`high`	Defines the primary task or focus area for AI assistance
context.inclusion	`medium`	Determines how much context from the current scope is included in AI prompts
code.modification	`high`	Indicates whether AI can modify code directly or only suggest changes
feedback.loop	`medium`	Controls if AI feedback should be iterative or final
error.handling	`low`	Defines how AI handles and suggests fixes for errors in code

Example: Configuring Priority Order

{
  "ai": {
    "core.task.focus": "high",
    "context.inclusion": "medium",
    "code.modification": "high",
    "feedback.loop": "medium",
    "error.handling": "low"
  }
}

Note: Priority levels can be adjusted dynamically based on project scope and task complexity.

7. Excluding Files from Instructions

Option	Values	Description
exclude	`string[]`	List of file paths or glob patterns to exclude from AI processing

Example: Exclude specific files from AI instructions

{
  "exclude": [
    "node_modules/**",
    "*.log",
    "dist/**/*.js"
  ]
}

Note: Glob patterns follow minimatch syntax. Files matching any exclude pattern will not be included in AI-assisted development workflows.

8. Debugging Instruction Matching Issues

Example: Debugging Misaligned Instructions

// Simulated instruction matching logic
const userQuery = "Implement a login form with validation";
const context = {
  projectType: "React",
  techStack: ["JavaScript", "CSS"],
  constraints: ["No external libraries"]
};

function matchInstruction(query, context) {
  const matched = {
    instruction: "Create a login form",
    confidence: 0.75,
    reasons: [
      "User query mentions login form",
      "Context includes React and JavaScript"
    ]
  };
  
  // Debug: Log matching process
  console.log("Query:", query);
  console.log("Context:", context);
  console.log("Matched Instruction:", matched.instruction);
  
  return matched;
}

matchInstruction(userQuery, context);

Issue	Description	Solution
Misaligned Instruction	Generated instruction does not match user intent	Review query and context to refine matching logic
Low Confidence Match	Match confidence below threshold (e.g., < 0.7)	Adjust matching weights or add more context
Overlapping Instructions	Multiple instructions match query with similar confidence	Implement instruction prioritization or user selection

Note: Use logging or debugging tools to inspect how AI models interpret user queries and match them to instructions.

Warning: Misaligned instructions can lead to incorrect code generation or developer confusion.

Debugging Steps

Log raw query and context data
Analyze instruction matching confidence scores
Verify that matched instructions align with user intent
Adjust matching criteria or training data if needed