Customizing for Your Project

Adapt agents to your specific project needs.

Table of Contents

Add Project Context

The most powerful customization is providing project context.

Step 1: Create the File

Create .github/copilot-instructions.md in your repository root.

Step 2: Document Your Project 

# Project Context

## Overview
[1-2 sentence description of what your project does]

## Tech Stack {#tech-stack}
- Backend: Node.js 18+ with Express
- Frontend: React 18 with TypeScript
- Database: PostgreSQL 14
- DevOps: Docker, Kubernetes

## Architecture {#architecture}
[Describe your architecture]

## Coding Standards {#coding-standards}

### JavaScript/TypeScript
- Use async/await, no callbacks
- Strict TypeScript mode
- ESLint + Prettier for formatting
- Jest for testing
- 80% code coverage minimum

### Node.js Specific
- Use dependency injection
- Middleware pattern for plugins
- Clean error handling with codes
- Structured logging (JSON format)

## Project Structure {#project-structure}

src/ ├── api/ # Express routes ├── services/ # Business logic ├── models/ # Data models ├── middleware/ # Express middleware ├── utils/ # Utilities └── tests/ # Test files

config/ ├── database.js # DB configuration └── app.js # App configuration


## Key Files & Standards {#key-files--standards}
- `package.json` - Dependencies (always npm ci in CI/CD)
- `.eslintrc.json` - Linting rules
- `.prettierrc` - Formatting
- `jest.config.js` - Testing config
- `Dockerfile` - Container setup

## Running the Project {#running-the-project}

### Local Development
```bash
npm install
npm run dev        # Starts on :3000

Testing 

npm test           # Run all tests
npm run test:cov   # With coverage

Building 

npm run build      # Compile TypeScript
npm run lint       # Check style

Dependencies to Know About

  • express - Web framework
  • sequelize - ORM for PostgreSQL
  • joi - Data validation
  • winston - Logging
  • jest - Testing

Important Constraints

  • Must maintain backward compatibility
  • No external API calls without rate limiting
  • All credentials through environment variables
  • Minimum Node 16 LTS
  • No direct database access from API (always use ORM)

Common Patterns in This Project

  • Middleware for auth/logging
  • Validation using Joi
  • Error responses with codes: { code, message, statusCode }
  • Async error handling with try/catch
  • Service layer for business logic

### Step 3: Agents Use It Automatically

Now when you:
- Ask @codebase to implement features → uses your architecture
- Ask @review to audit code → checks against your standards
- Ask @docs to create README → references your tech stack
- Ask @orchestrator to coordinate → applies your patterns

**All without additional context!**

---

## Customize Agent Behavior {#customize-agent-behavior}

### Modify an Agent

Agents are defined in `.github/agents/`:

```bash
.github/agents/
├── codebase.agent.md
├── planner.agent.md
├── orchestrator.agent.md
├── docs.agent.md
├── review.agent.md
└── em-advisor.agent.md

Example: Customize @review

Edit .github/agents/review.agent.md:

---
name: review
description: Code review specialist for our standards
tools: [...]
---

# Code Review Agent

## Our Review Standards

### Security (Critical)
- [ ] No hardcoded secrets
- [ ] Input validation on all endpoints
- [ ] SQL injection prevention
- [ ] Rate limiting present
- [ ] Error messages don't leak info

### Performance (High)
- [ ] No N+1 queries
- [ ] Caching strategy defined
- [ ] Load tested at 1000 concurrent users
- [ ] Database indexes on foreign keys

Create Custom Prompts

Add project-specific prompts for common tasks.

Step 1: Create Prompt File

Create .github/prompts/database-migration.prompt.md:

---
description: Generate database migration
agent: codebase
---

# Database Migration

Generate a database migration for [change]:

## Requirements
- Use Sequelize migrations
- Support rollback
- Test on PostgreSQL 14
- Add to migration history
- Update models if needed

Step 2: Use in Copilot Chat 

/database-migration Add user last_login timestamp

Add Coding Standards for Your Stack

Create .github/instructions/node-express.instructions.md:

---
description: Node.js Express best practices
applyTo: '**/*.js,**/*.ts'
---

# Node.js Express Standards

## Express Routing
- Use async middleware
- Always handle errors
- Validate request data with Joi
- Return consistent JSON response format

## Error Handling
```javascript
// Middleware format
const asyncHandler = (fn) => (req, res, next) => 
    Promise.resolve(fn(req, res, next)).catch(next);

app.post('/users', asyncHandler(async (req, res) => {
    const user = await createUser(req.body);
    res.json({ success: true, data: user });
}));

Response Format 

{
  success: boolean,
  code: string,        // e.g., "USER_CREATED"
  message: string,
  data: any,
  statusCode: number
}


---

## Make Standards Language-Specific

### For TypeScript Only

Create `.github/instructions/typescript-only.instructions.md`:

```markdown
---
description: TypeScript-specific standards
applyTo: '**/*.ts'
---

# TypeScript Standards

[Your specific TypeScript rules]

For React Components

Create .github/instructions/react.instructions.md:

---
description: React component standards
applyTo: '**/components/**/*.tsx'
---

# React Component Standards

[Your component patterns]

Update Instructions Over Time

As your project evolves:

  1. Agent proposes improvements at task completion
  2. You review updates to .github/copilot-instructions.md
  3. Approve or modify the context
  4. All future sessions use new context

This creates a continuously improving knowledge base!

Template: Minimal Project Context

For quick setup, use this template:

# Project

## Tech
- [Your tech stack here]

## Standards
- Type hints/types required
- 80% test coverage
- No hardcoded secrets

## Architecture
[Brief overview]

## How to Run
```bash
[Your setup commands]

Key Dependencies

  • [Your main libraries]

---

## Template: Comprehensive Project Context {#template-comprehensive-project-context}

For mature projects:

```markdown
# [Project Name]

[Full context from the example above...]

## Domain Knowledge
[Business logic, special rules]

## Performance Requirements
[SLA, capacity requirements]

## Security Requirements
[Compliance, data sensitivity]

## Integration Points
[External APIs, services]

## Deployment Process
[How code gets to production]

## Monitoring & Alerts
[Key metrics, dashboards]

## Team Conventions
[Naming, patterns, idioms]

Troubleshooting Customization

Q: Agent not using my context?
A: Make sure .github/copilot-instructions.md exists in repository root.

Q: Agent ignoring my standards?
A: Add standards to .github/instructions/ files with proper applyTo patterns.

Q: Custom prompt not showing?
A: Verify file is in .github/prompts/ with .prompt.md extension.

Next Steps

Back to top

Copyright © 2025 Shehab Elhadidy. Licensed under the MIT License.