AI Playbook - Business Analysis

Here is some practical guidance on how to set up your own AI Agent, whom you can talk to about the code and database in your project. After successful configuration, you will be able to ask questions (and get reliable answers!) regarding how the software works, what DB schema is, how services are interconnected, drawing UML sequence diagrams etc.

Core Principles: All recommendations in this playbook align with Xebia's official Core Principles for Working with AI. Refer to that document for the foundational rules that govern every AI interaction at Xebia.

How this Playbook is organized

In this document, you will find step-by-step manuals on how to:

create your own AI Agent in VS Code
add additional security layer to the code (so you do not commit any changes by accident)
configure GIT to download a code repository to your local machine
configure SQL extension to be able to interact with the data on your local machine

1. BA.agent.md

Here are the instructions to set up a BA agent for your codebase in VS Code. You can set up an agent and - if needed for your project - add guardrails to be doubly sure that none of the code is changed.

General rule no.1: If something doesn't work for you, just ask agent to fix it 🙂 General rule no.2: Use Ask or Plan instead of Agent mode in Github Copilot chat window.

VS Code agent.md configuration

Create and place the file (BA.agent.md) in your workspace root in .github\agents folder within a VS Code workspace
Reference it (choose from the list) when you want the BA agent to analyze features, generate user stories, or provide gap analysis
Contents of the BA.agent.md file:

# Role: AI Business Analyst & System Architect

You are a specialized Business Analyst (BA) agent. Your primary objective is to bridge the gap between business requirements and the existing technical implementation. 

## 🚫 CRITICAL RESTRICTION: READ-ONLY MODE
1. **NO CODE CHANGES:** You are strictly forbidden from writing, modifying, or deleting any code files.
2. **NO COMMITS:** You must never attempt to stage, commit, or push changes to the repository.
3. **NO REFACTORING:** Even if requested, do not provide "code fixes." Instead, describe the logic required in plain English or pseudocode within the chat.

## 🎯 Core Mission
Your purpose is to provide high-level insights for stakeholders. You act as a "Code-to-Business Translator."

### 1. Code Explanation
- When asked about a feature, trace the logic through the files and explain **how** it works in business terms.
- Identify dependencies and business rules hidden in the logic.
- Use flowcharts (Mermaid syntax) to visualize complex logic when helpful.

### 2. Requirement Engineering & User Stories
When a user requests a new feature or change, your task is to:
- Analyze the existing code to see where this feature would fit.
- Generate structured **User Stories** using the following template:
    - **Title:** [Brief Feature Name]
    - **User Story:** As a [Persona], I want to [Action], so that [Value].
    - **Acceptance Criteria:** (List of specific conditions that must be met).
    - **Technical Impact:** (High-level list of existing modules/files that will be affected).

### 3. Gap Analysis
- Identify if a requested feature conflicts with existing system logic.
- Flag potential "edge cases" that the user might have missed in their request.

## 🛠 Operational Guidelines
- **Context First:** Always start by scanning the relevant directory structure to understand the scope before answering.
- **Language:** Maintain a professional, analytical, and concise tone. Avoid developer jargon unless explaining a specific technical constraint to a stakeholder.
- **Clarity:** If a request is ambiguous, ask clarifying "Discovery Questions" before proposing a solution.

Now you are ready to clone GIT repository (and fork it if needed) and/or connect DB to VS Code.

It is also beneficial to install mermaid.js extension for VS Code - you will be able to see diagrams in VS Code - quite handy!

2. VS Code safety guardrails

Talk to your Tech Lead about additional safety guardrails. If needed feel free to use one or all below approaches.

1. The "Hard Stop": Git Pre-Commit Hook

Even if the AI manages to write code to a file, you can prevent that code from ever being committed to the repository. This is the most effective technical guardrail.

Create a file named .git/hooks/pre-commit (or use a tool like Husky) with this script:

Bash

#!/bin/sh
# Block all commits to ensure a Read-Only Analyst environment
echo "❌ ERROR: This is a Read-Only Analyst environment. Commits are disabled."
exit 1

Result: Any attempt to git commit (by the AI or the human) will fail instantly with that message.

2. VS Code Workspace Settings (`.vscode/settings.json`)

You can disable the AI's "intrusive" features so it doesn't even try to suggest code inline while the BA is reading. Add this to your project's .vscode/settings.json:

JSON

{
  // Disable Ghost Text/Inline completions to keep the UI clean for analysis
  "github.copilot.editor.enableAutoCompletions": false,
  
  // Prevent the AI from automatically triggering actions
  "github.copilot.enable": {
    "*": true,
    "plaintext": true,
    "markdown": true
  },

  // Ensure the BA doesn't accidentally edit files
  "files.readonlyInclude": {
    "**/*": true
  },

  // Visual cue: Change the title bar color so the BA knows they are in "Analyst Mode"
  "workbench.colorCustomizations": {
    "titleBar.activeBackground": "#2d3436",
    "titleBar.activeForeground": "#fab1a0"
  }
}

Note: files.readonlyInclude makes the files read-only within the VS Code editor itself, which provides a UI warning if anyone tries to type in the code.

3. Repository-Level "Protection" (If using GitHub)

If this repository is hosted on GitHub/GitLab, use Branch Protection Rules:

Restrict Pushes: Lock the main or develop branches so that no one (including the AI agent) can push directly.
Require Pull Request: Force all changes through a PR that requires an approval. Since the AI won't have "Approval" authority, it can't merge its own logic.

3. GIT configuration

Here you can find a step-by-step plan from total scratch (Windows) to cloning and working with GitHub repos

Create your GitHub account

Go to https://github.com/signup
Verify email and enable 2FA (recommended, often required for org repos).
Set your profile name and username.

Install Git on Windows

Download from https://git-scm.com/download/win
Run installer with defaults (safe for beginners).
Important options to keep:
- Git from the command line and also from 3rd-party software
- Use bundled OpenSSH
- Use Git Credential Manager
Restart terminal after install.

Verify Git installation Open PowerShell and run:

git --version

You should see something like git version 2.x.x.

Set your Git identity (one-time)

git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"

Check it:

git config --global --list

Pick authentication method (recommended: HTTPS + browser sign-in) For most beginners on Windows, easiest path is HTTPS with Git Credential Manager.

First clone/push will open browser auth automatically.
No manual token handling needed in most cases.

Clone your repository From the repo page on GitHub:

Click Code → choose HTTPS → copy URL (e.g. https://github.com/org/repo.git)

In PowerShell:

cd C:\Users\YourUser\Documents
git clone https://github.com/org/repo.git
cd repo

4. SQL Connection

SQL and MySQL Workbench
There is no official GitHub Copilot plugin for SQL Workbench. There is also no official native Copilot integration inside MySQL Workbench.

What works well instead:

Install DB Client on your computer (e.g. SQL Server Management Studio) and configure DB
Use VS Code with GitHub Copilot + a SQL extension (e.g. SQL Server).
Connect VS Code to your database.

Good prompt examples for Copilot:

“Write a query to find top 10 customers by revenue in the last 90 days.”
“Optimize this query and explain index recommendations.”
“Convert this MySQL query to PostgreSQL syntax.”
"Draw diagram of DB in mermaid.js"