ai-docs/docs/ai/overview.md

AI Overview

Start Here

AI tools help with drafting, refactoring, explaining code, and accelerating routine tasks. They are not a replacement for engineering judgment, security review, or domain knowledge.

What To Expect In The First 30 Minutes

1. Confirm you have access to GitHub Copilot Enterprise.
2. Install the editor plugin for your platform.
3. Run a simple prompt to verify suggestions appear.
4. Read the usage and token guidance to avoid accidental overuse.

What AI Is and Is Not

• AI is a productivity assistant that can suggest code, summarize context, and propose solutions.
• AI is not a source of truth. Always validate outputs with tests, code review, and domain checks.

Example (Good vs Risky)

Good: "Summarize this file and list the top 3 risks." Risky: "Rewrite this subsystem without review." (Always review large changes.)

GitHub Copilot Enterprise

What It Is

Copilot is an AI coding assistant that integrates with editors and chats to help you write and understand code.

Access Requirements

• You must be provisioned for Copilot Enterprise by the org.
• You must sign in with your GitHub account that has access.

Setup Steps (High-Level)

1. Confirm access with your team or admin.
2. Sign in to GitHub in your editor or plugin.
3. Verify Copilot is enabled in editor settings.
4. Run a quick prompt to validate it works.

What You Should See

• A Copilot icon or status indicator in your editor.
• Inline code suggestions as you type.
• A chat panel that can answer questions.

Quick Access Checklist

• GitHub account is linked to the org.
• SSO or required auth flow is completed.
• Copilot is enabled in the editor or plugin settings.

Terminology

• Copilot: The AI assistant integrated into your editor.
• Chat: The conversational interface in your editor.
• Agents: Structured workflows that break work into steps.
• Skills: Reusable knowledge or workflows the assistant can apply.
• Tokens: The usage units that track AI consumption.

Key Repo Files (Why They Exist)

These files explain how the AI docs are organized and how contributors should work. Each one has a different job.

Agents.md

What it is: The workflow rules for using AI in this repo.

Why you create it: It keeps requests consistent so changes are scoped, reviewable, and repeatable.

What to include:

• Request structure (goal, inputs, output, verification).
• Plan-first guidance for multi-step changes.
• Sync rule: keep PRD.md and README.md aligned when workflows or scope change.

Project example: See Agents.md for the request template and contribution workflow used in this repo.

PRD.md

What it is: The product requirements for the documentation set.

Why you create it: It anchors scope and success metrics so the docs do not drift.

What to include:

• Problem statement, goals, and non-goals.
• Target audience and user stories.
• Content requirements (step-by-step guidance and examples).
• Definition of done and sync expectations.

Project example: See PRD.md for the requirements and definition of done used here.

README.md

What it is: The entry point for contributors and readers who need quick orientation.

Why you create it: It tells people what the repo is, where to start, and how to contribute.

What to include:

• Repo purpose and audience.
• Where to start (index, overview, setup guides).
• Contribution habits and publishing steps.

Project example: See README.md for the start-here links and local workflow.

Chat Types In Plain English

Copilot chat has four modes. Pick the smallest one that fits the task.

Ask: Quick questions, summaries, or explanations. Example: "Summarize this file in 5 bullets and list 2 risks."

Edit: Small, specific changes with constraints. Example: "Update this function to return nil when the input is empty. Keep behavior the same otherwise."

Plan: A step-by-step plan before edits. Example: "Give me a 6-step plan to add caching to this service. Wait for approval before edits."

Agent: Multi-step work across files with checks. Example: "Refactor these two files, update unit tests, then summarize the changes and test results."

Example: Chat vs Agents

• Chat: "What does this function do?"
• Agent: "Plan and refactor this module, then list tests to add."

First Prompt (Safe)

Try a small, safe prompt to confirm everything is working:

Summarize what this file does in 3 bullet points.

Guardrails And Good Habits

• Keep prompts scoped to a single task.
• Ask for a plan before large changes.
• Verify outputs with tests and review.
• Avoid sharing secrets or sensitive data.

Example: Safe Prompt

"Refactor only the validation logic in this file. Keep behavior the same and list tests to update."

Getting Help

• Ask your team lead or the AI docs owner.
• Use the escalation guidance in Troubleshooting and FAQ.