158 lines
5.1 KiB
Markdown
158 lines
5.1 KiB
Markdown
# Cross-Platform AI Usage
|
|
|
|
## Instructions (Always-On Rules)
|
|
Instructions are repo-scoped rules that auto-apply based on file patterns. They are always on and do not need to be invoked.
|
|
|
|
Where they live:
|
|
- Repo instructions directory (for example, [assets/instructions/](../../assets/instructions/))
|
|
- Editor or org-level instruction files when configured by your team
|
|
|
|
## Agents.md
|
|
### What It Is
|
|
Agents define a structured workflow so tasks are broken into clear steps, with explicit inputs and outputs.
|
|
|
|
### How to Use It
|
|
1. Read [Agents.md](../../Agents.md).
|
|
2. Choose a workflow that matches your task.
|
|
3. Provide the inputs in a short, bounded request.
|
|
|
|
### Example Request
|
|
Example prompt:
|
|
|
|
```text
|
|
Goal: Improve readability in this module
|
|
Inputs: src/foo/Bar.kt, keep behavior the same
|
|
Output: A small refactor and a short summary
|
|
Verification: No tests needed
|
|
```
|
|
|
|
### When to Use Agents vs Chat
|
|
- Use agents for multi-step tasks like refactors, doc audits, or migrations.
|
|
- Use chat for quick questions or one-off explanations.
|
|
|
|
## Agents vs Skills (Quick Compare)
|
|
- Agents are full modes/personas that control behavior end-to-end. They can be stored in a repo or a user-level folder.
|
|
- Skills are focused workflows you load for specific tasks. They are typically installed globally via the approved skills directory.
|
|
|
|
## Chat Modes In Copilot
|
|
Ask: Quick Q and A or summaries.
|
|
Edit: Targeted file edits with constraints.
|
|
Plan: Planning only, no edits yet.
|
|
Agent: Multi-step work across files or tools.
|
|
|
|
Example prompts:
|
|
```text
|
|
Ask: Explain this error message and list the top 3 likely fixes.
|
|
Edit: In this file, extract a helper function for validation and keep behavior the same.
|
|
Plan: Provide a 5-step plan to split this class into smaller components. Wait for approval.
|
|
Agent: Refactor the service layer, update tests, run the test task, and summarize results.
|
|
```
|
|
|
|
### Request Template
|
|
Use this structure to get consistent results:
|
|
|
|
```text
|
|
Goal: <one sentence>
|
|
Inputs: <files, constraints, context>
|
|
Output: <expected deliverable>
|
|
Verification: <tests or checks>
|
|
```
|
|
|
|
## Prompting Patterns
|
|
Example prompts:
|
|
```text
|
|
Refactors: Refactor this file to improve readability without changing behavior.
|
|
Tests: Add unit tests for this service. Keep the existing public API.
|
|
Debugging: Explain this error and list likely fixes in order.
|
|
Understanding code: Summarize what this module does and call out risks.
|
|
```
|
|
|
|
## Prompting Anti-Patterns (And Fixes)
|
|
Common mistakes and better alternatives:
|
|
|
|
Example prompts:
|
|
```text
|
|
Too broad: Fix everything in this project.
|
|
Better: Refactor this file to remove duplication. Do not change behavior.
|
|
|
|
Too vague: Make this code better.
|
|
Better: Improve naming and add comments only where logic is complex.
|
|
|
|
Missing inputs: Update the service to handle retries.
|
|
Better: Update ServiceA in src/service/ServiceA.kt to retry 2 times on 5xx. Keep API the same.
|
|
```
|
|
|
|
### Example: Too Broad vs Scoped
|
|
Example prompts:
|
|
```text
|
|
Too broad: Fix everything in this project.
|
|
Scoped: Refactor this file to remove duplication. Do not change behavior.
|
|
```
|
|
|
|
## Plan-First Workflow
|
|
1. Ask for a short plan.
|
|
2. Approve or adjust the plan.
|
|
3. Ask for targeted changes.
|
|
4. Verify with tests or review.
|
|
|
|
### Example Plan Request
|
|
Example prompt:
|
|
```text
|
|
Provide a 5-step plan to refactor this module. Wait for approval before edits.
|
|
```
|
|
|
|
## Starter Prompts (Copy/Paste)
|
|
Use these when you are not sure where to begin:
|
|
|
|
Example prompts:
|
|
```text
|
|
Summarize this file in 5 bullets and list 2 risks.
|
|
Refactor this function to remove duplication. Keep behavior the same.
|
|
List tests I should add for this change.
|
|
Explain this error and propose the top 3 fixes.
|
|
Create a 5-step plan to split this class into smaller components.
|
|
```
|
|
|
|
## Connecting Skills
|
|
- Use skills for tasks with known workflows.
|
|
- Combine multiple skills when a task spans domains.
|
|
- Pass concise context between steps to reduce repetition.
|
|
|
|
## Efficiency Tips
|
|
- Keep prompts small and scoped.
|
|
- Reuse context from earlier steps instead of repeating it.
|
|
- Ask for summaries before asking for edits.
|
|
|
|
### Example Summary Request
|
|
Example prompt:
|
|
```text
|
|
Summarize the decisions so far in 6 bullets so I can start a new chat.
|
|
```
|
|
|
|
## MCP (Model Context Protocol) - Cross-Platform Overview
|
|
MCP is an open standard that lets tools and agents interact with real systems. In plain language, MCP lets the assistant "do" things (like run builds or fetch logs) instead of just talking about them.
|
|
|
|
### How MCP Helps In A Workflow
|
|
Think of MCP as a set of safe, structured buttons the assistant can press. You ask a question, the assistant calls a tool, and it returns a clear result.
|
|
|
|
### Common MCP Use Cases (All Platforms)
|
|
- Run builds and tests
|
|
- Fetch logs or diagnostics
|
|
- Query project configuration
|
|
- Generate previews or reports
|
|
|
|
### Example Workflow
|
|
1. Ask the assistant to run a build.
|
|
2. The MCP tool runs it and returns the result.
|
|
3. You ask for a summary and next steps.
|
|
|
|
### Example Prompt
|
|
Example prompt:
|
|
```text
|
|
Use the build MCP tool to run the build and summarize any errors.
|
|
```
|
|
|
|
### Where To Learn More
|
|
- iOS examples: see [iOS Setup](ios.md)
|
|
- Android examples: see [Android Setup](android.md)
|