157 lines
5.9 KiB
Markdown
157 lines
5.9 KiB
Markdown
# 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)
|
|
Example prompts:
|
|
```text
|
|
Good: Summarize this file and list the top 3 risks.
|
|
Risky: Rewrite this subsystem without review.
|
|
```
|
|
|
|
## 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.
|
|
|
|
## Instructions (Repo Rules)
|
|
Instructions are repo-scoped rule files that auto-apply based on file patterns. They set coding or documentation standards the assistant must follow when editing matching files.
|
|
|
|
Where they live:
|
|
- The repo-level instructions directory (for example, [instructions/](../../instructions/))
|
|
- Editor or org-level instruction files when configured by your team
|
|
|
|
Instructions are always-on defaults. Agents and skills are optional and only used when you explicitly invoke them.
|
|
|
|
## Agents vs Skills (Where They Live)
|
|
Agents are full personas or modes (for example, Task Researcher) that control how the assistant behaves end-to-end. Skills are focused, reusable workflows (for example, webapp-testing) that the assistant can load for a specific task.
|
|
|
|
Where they live:
|
|
- Agents can be stored in a repo (project-specific) or in a user-level folder for global reuse.
|
|
- Skills are typically installed globally via the approved skills directory and synced with a manifest.
|
|
|
|
If you need the official agent assets repo, ask your team lead or check your internal setup docs.
|
|
|
|
## 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](../../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](../../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](../../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.
|
|
Edit: Small, specific changes with constraints.
|
|
Plan: A step-by-step plan before edits.
|
|
Agent: Multi-step work across files with checks.
|
|
|
|
Example prompts:
|
|
```text
|
|
Ask: Summarize this file in 5 bullets and list 2 risks.
|
|
Edit: Update this function to return nil when the input is empty. Keep behavior the same otherwise.
|
|
Plan: Give me a 6-step plan to add caching to this service. Wait for approval before edits.
|
|
Agent: Refactor these two files, update unit tests, then summarize the changes and test results.
|
|
```
|
|
|
|
### Example: Chat vs Agents
|
|
Example prompts:
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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
|
|
Example prompt:
|
|
```text
|
|
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](troubleshooting.md).
|