Add comprehensive agentic coding documentation
- Add 6 MCP server documentation pages (bc-code-intelligence, al-dependency, azure-devops, serena, al-objid, clockify) - Add AI Coding Agents documentation (GitHub Copilot, Claude, Cursor) - Add Getting Started section (what is agentic coding, setup, prompting, best practices, limitations, glossary) - Add Getting More section (code review, documentation, telemetry examples) - Add Community Resources placeholders (articles, videos, tools) - Update Tools section to focus on MCP servers instead of VSCode extensions
This commit is contained in:
Jeremy Vyska
parent
3254d9b7e8
commit
4db38ba4d3
28 changed files with 8152 additions and 0 deletions
20
content/docs/agentic-coding/GettingStarted/_index.md
Normal file
20
content/docs/agentic-coding/GettingStarted/_index.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
---
|
||||
title: "Getting Started"
|
||||
linkTitle: "Getting Started"
|
||||
weight: 10
|
||||
description: >
|
||||
Essential concepts and practices for working with AI coding assistants
|
||||
---
|
||||
|
||||
This section covers the fundamentals you need to start working effectively with AI-powered coding assistants in your AL development workflow.
|
||||
|
||||
## In This Section
|
||||
|
||||
- **[What is Agentic Coding](what-is-agentic-coding)** - Understanding the core concepts and benefits
|
||||
- **[Glossary](glossary)** - Common terms and concepts explained
|
||||
- **[Setting Up Your Environment](setup)** - Configure your development environment for AI assistance
|
||||
- **[Effective Prompting](effective-prompting)** - Learn how to communicate clearly with AI assistants
|
||||
- **[Best Practices](best-practices)** - Guidelines for successful AI-assisted development
|
||||
- **[Understanding Limitations](limitations)** - Know when to use (and not use) AI assistance
|
||||
|
||||
Start with understanding the concepts, then move through the practical setup and techniques to get the most value from your AI coding assistant.
|
||||
415
content/docs/agentic-coding/GettingStarted/best-practices.md
Normal file
415
content/docs/agentic-coding/GettingStarted/best-practices.md
Normal file
|
|
@ -0,0 +1,415 @@
|
|||
---
|
||||
title: "Best Practices"
|
||||
linkTitle: "Best Practices"
|
||||
weight: 4
|
||||
description: >
|
||||
Guidelines for successful AI-assisted AL development
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
AI coding assistants are powerful tools, but they work best when used thoughtfully. This guide provides best practices for integrating AI assistance into your AL development workflow.
|
||||
|
||||
## General Principles
|
||||
|
||||
### 1. AI Augments, Not Replaces
|
||||
**You are still the developer.** The AI is a tool to enhance your productivity, not a replacement for your expertise.
|
||||
|
||||
✅ **Good Approach**:
|
||||
- Use AI to generate boilerplate code
|
||||
- Review and understand all generated code
|
||||
- Make architectural decisions yourself
|
||||
- Validate business logic
|
||||
|
||||
❌ **Poor Approach**:
|
||||
- Blindly accept all AI suggestions
|
||||
- Skip code review for AI-generated code
|
||||
- Let AI make design decisions
|
||||
- Assume AI understands your business requirements
|
||||
|
||||
### 2. Trust, but Verify
|
||||
Always review AI-generated code:
|
||||
|
||||
```al
|
||||
// AI might generate this:
|
||||
procedure CalculateDiscount(Amount: Decimal): Decimal
|
||||
begin
|
||||
exit(Amount * 0.1); // Always 10% discount
|
||||
end;
|
||||
|
||||
// But you need to verify it matches requirements:
|
||||
// - Is 10% correct for all scenarios?
|
||||
// - Should it vary by customer type?
|
||||
// - Are there discount limits?
|
||||
// - Should it read from setup?
|
||||
```
|
||||
|
||||
### 3. Provide Good Context
|
||||
Better context = better results:
|
||||
|
||||
✅ **Provide**:
|
||||
- Clear file and folder names
|
||||
- XML documentation comments
|
||||
- Descriptive variable names
|
||||
- Project README with conventions
|
||||
- Open related files
|
||||
|
||||
❌ **Avoid**:
|
||||
- Generic names like `Temp1`, `DoStuff`
|
||||
- Undocumented complex logic
|
||||
- Mixing unrelated code in one file
|
||||
|
||||
## Code Generation Best Practices
|
||||
|
||||
### Start with Structure
|
||||
Generate scaffolding first, then refine:
|
||||
|
||||
1. **First**: Generate basic structure
|
||||
```
|
||||
Create a codeunit skeleton for "Sales Order Processor" with procedures for:
|
||||
- ValidateOrder
|
||||
- CalculateTotals
|
||||
- ProcessPayment
|
||||
- PostOrder
|
||||
```
|
||||
|
||||
2. **Then**: Implement each procedure
|
||||
```
|
||||
Implement the ValidateOrder procedure with these checks:
|
||||
- Customer exists
|
||||
- All lines have positive quantities
|
||||
- Credit limit not exceeded
|
||||
```
|
||||
|
||||
### Review Generated Code
|
||||
Check AI-generated code for:
|
||||
|
||||
**Correctness**
|
||||
- Does it do what you asked?
|
||||
- Are there edge cases not handled?
|
||||
- Is the logic sound?
|
||||
|
||||
**AL Best Practices**
|
||||
- Proper error handling
|
||||
- Appropriate use of transactions
|
||||
- Correct field validations
|
||||
- No unnecessary database calls
|
||||
|
||||
**Business Central Standards**
|
||||
- Correct use of BC APIs
|
||||
- Proper event patterns
|
||||
- Standard naming conventions
|
||||
- Application area settings
|
||||
|
||||
**Performance**
|
||||
- Efficient database queries
|
||||
- Appropriate filtering
|
||||
- Minimal record iterations
|
||||
- Proper use of FindSet vs FindFirst
|
||||
|
||||
### Iterate and Refine
|
||||
Don't expect perfection on first try:
|
||||
|
||||
```
|
||||
// Initial prompt
|
||||
Create a procedure to import customers from CSV
|
||||
|
||||
// After reviewing generated code
|
||||
Add validation for required fields: Name and Email
|
||||
|
||||
// After further review
|
||||
Add error logging and return a list of failed imports
|
||||
|
||||
// Final refinement
|
||||
Add telemetry tracking for import metrics
|
||||
```
|
||||
|
||||
## Code Review with AI
|
||||
|
||||
### Use AI for Initial Review
|
||||
AI can catch common issues:
|
||||
|
||||
```
|
||||
Review this code for:
|
||||
- Potential bugs
|
||||
- Performance issues
|
||||
- AL best practice violations
|
||||
- Missing error handling
|
||||
```
|
||||
|
||||
### Don't Skip Human Review
|
||||
AI review is a supplement, not a replacement:
|
||||
|
||||
- **AI catches**: Syntax issues, common patterns, style violations
|
||||
- **You catch**: Business logic errors, architectural concerns, context-specific issues
|
||||
|
||||
### Review AI's Review
|
||||
The AI might miss context:
|
||||
|
||||
```al
|
||||
// AI might flag this as inefficient:
|
||||
Customer.SetRange("No.", CustNo);
|
||||
if Customer.FindFirst() then
|
||||
Customer.Name := NewName;
|
||||
|
||||
// But might miss that in your context, you're in a loop
|
||||
// processing thousands of customers, which is inefficient
|
||||
```
|
||||
|
||||
## Documentation with AI
|
||||
|
||||
### Generate Drafts, Then Personalize
|
||||
Use AI for documentation drafts:
|
||||
|
||||
```
|
||||
Generate XML documentation for this codeunit
|
||||
```
|
||||
|
||||
Then review and enhance:
|
||||
- Add business context
|
||||
- Include usage examples
|
||||
- Document assumptions
|
||||
- Note dependencies
|
||||
|
||||
### Keep Documentation Updated
|
||||
When AI generates code changes:
|
||||
|
||||
```
|
||||
Update this procedure and its XML documentation to include the new parameter
|
||||
```
|
||||
|
||||
### Create User-Facing Documentation
|
||||
AI can help with user docs too:
|
||||
|
||||
```
|
||||
Create user documentation explaining how to set up customer discount categories.
|
||||
Target audience: Business users, not developers.
|
||||
```
|
||||
|
||||
## Testing with AI
|
||||
|
||||
### Generate Test Scaffolding
|
||||
```
|
||||
Create a test codeunit structure for testing the Sales Order Processor
|
||||
Include test methods for each public procedure
|
||||
```
|
||||
|
||||
### Create Test Data Setup
|
||||
```
|
||||
Create a helper procedure that sets up test data:
|
||||
- One customer with normal credit limit
|
||||
- One customer with exceeded credit
|
||||
- Sample items with prices
|
||||
- Sales header with lines
|
||||
```
|
||||
|
||||
### Don't Rely Only on AI Tests
|
||||
AI-generated tests might miss:
|
||||
- Edge cases specific to your business
|
||||
- Integration scenarios
|
||||
- Performance testing needs
|
||||
- User acceptance criteria
|
||||
|
||||
## Refactoring with AI
|
||||
|
||||
### Safe Refactoring Steps
|
||||
|
||||
1. **Ensure Tests Exist**
|
||||
```
|
||||
Create tests for this procedure before we refactor it
|
||||
```
|
||||
|
||||
2. **Refactor with AI**
|
||||
```
|
||||
Refactor this procedure to extract the discount calculation into a separate function
|
||||
```
|
||||
|
||||
3. **Verify Tests Still Pass**
|
||||
Run your test suite to confirm behavior unchanged
|
||||
|
||||
4. **Review Changes**
|
||||
Understand what changed and why
|
||||
|
||||
### When to Refactor with AI
|
||||
✅ **Good for**:
|
||||
- Extracting methods
|
||||
- Renaming variables
|
||||
- Applying consistent formatting
|
||||
- Adding error handling
|
||||
- Modernizing deprecated APIs
|
||||
|
||||
❌ **Be Careful with**:
|
||||
- Complex business logic changes
|
||||
- Architectural changes
|
||||
- Database schema modifications
|
||||
- Integration point changes
|
||||
|
||||
## Learning from AI
|
||||
|
||||
### Use AI as a Learning Tool
|
||||
|
||||
**Ask for Explanations**:
|
||||
```
|
||||
Explain why this code uses Commit instead of direct posting
|
||||
```
|
||||
|
||||
**Request Alternatives**:
|
||||
```
|
||||
Show me three different ways to implement this validation,
|
||||
with pros and cons of each
|
||||
```
|
||||
|
||||
**Learn Patterns**:
|
||||
```
|
||||
Show me the standard AL pattern for implementing a document posting routine
|
||||
```
|
||||
|
||||
### Build Your Knowledge
|
||||
Don't become dependent:
|
||||
- Understand the code, don't just use it
|
||||
- Learn the patterns being used
|
||||
- Research unfamiliar APIs or techniques
|
||||
- Practice writing code without AI assistance
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### AI and Code Performance
|
||||
AI doesn't automatically write optimal code:
|
||||
|
||||
```al
|
||||
// AI might generate this:
|
||||
for i := 1 to Customer.Count do begin
|
||||
Customer.Get(i);
|
||||
ProcessCustomer(Customer);
|
||||
end;
|
||||
|
||||
// You should refactor to:
|
||||
if Customer.FindSet() then
|
||||
repeat
|
||||
ProcessCustomer(Customer);
|
||||
until Customer.Next() = 0;
|
||||
```
|
||||
|
||||
### Review for Performance
|
||||
Always check AI-generated code for:
|
||||
- Database query efficiency
|
||||
- Unnecessary loops
|
||||
- Proper use of filters
|
||||
- Appropriate use of temporary tables
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Don't Share Sensitive Data
|
||||
Be careful what's in your workspace:
|
||||
- Production connection strings
|
||||
- Customer data
|
||||
- API keys or secrets
|
||||
- Proprietary algorithms
|
||||
|
||||
### Review Security Aspects
|
||||
AI might not catch security issues:
|
||||
|
||||
```al
|
||||
// AI might generate this:
|
||||
procedure ExecuteSQL(SQLStatement: Text)
|
||||
begin
|
||||
// Direct SQL execution - potential SQL injection!
|
||||
end;
|
||||
|
||||
// You need to catch security concerns
|
||||
```
|
||||
|
||||
## Collaboration Best Practices
|
||||
|
||||
### Team Standards
|
||||
Establish team guidelines:
|
||||
- When to use AI assistance
|
||||
- Required review process for AI code
|
||||
- Documentation requirements
|
||||
- Testing standards
|
||||
|
||||
### Code Review Process
|
||||
For AI-generated code:
|
||||
1. Mark commits that include AI-generated code
|
||||
2. Extra scrutiny during review
|
||||
3. Explain AI usage in PR descriptions
|
||||
4. Share learnings with the team
|
||||
|
||||
### Knowledge Sharing
|
||||
Help your team:
|
||||
- Share effective prompts
|
||||
- Document successful patterns
|
||||
- Discuss AI limitations found
|
||||
- Teach AI-assisted techniques
|
||||
|
||||
## When NOT to Use AI
|
||||
|
||||
### AI is Not Ideal For:
|
||||
|
||||
**Critical Security Code**
|
||||
- Authentication and authorization
|
||||
- Encryption implementations
|
||||
- Security-sensitive validations
|
||||
|
||||
**Highly Specialized Logic**
|
||||
- Unique business rules requiring deep domain knowledge
|
||||
- Complex calculations with many edge cases
|
||||
- Industry-specific compliance requirements
|
||||
|
||||
**Exploration and Learning**
|
||||
- When you're trying to learn a new concept
|
||||
- When you need to deeply understand the solution
|
||||
- When the journey is as important as the destination
|
||||
|
||||
**Quick, Simple Tasks**
|
||||
- You can type it faster than explaining it
|
||||
- It's simpler to do it yourself
|
||||
- The prompt would be longer than the code
|
||||
|
||||
## Measuring Success
|
||||
|
||||
### Track Your Productivity
|
||||
Monitor how AI affects your work:
|
||||
- Time saved on boilerplate code
|
||||
- Reduction in syntax errors
|
||||
- Faster documentation creation
|
||||
- More time for design and testing
|
||||
|
||||
### Quality Metrics
|
||||
Ensure quality isn't suffering:
|
||||
- Bug rates in AI-assisted code
|
||||
- Code review findings
|
||||
- Test coverage
|
||||
- Performance benchmarks
|
||||
|
||||
### Continuous Improvement
|
||||
- Refine your prompting skills
|
||||
- Learn from unsuccessful attempts
|
||||
- Share successes with your team
|
||||
- Update your practices as AI tools evolve
|
||||
|
||||
## Quick Reference: Do's and Don'ts
|
||||
|
||||
### ✅ Do
|
||||
- Review all AI-generated code
|
||||
- Provide clear, specific prompts
|
||||
- Use AI for boilerplate and repetitive tasks
|
||||
- Learn from AI-generated examples
|
||||
- Test AI-generated code thoroughly
|
||||
- Keep documentation updated
|
||||
- Share knowledge with your team
|
||||
|
||||
### ❌ Don't
|
||||
- Blindly accept AI suggestions
|
||||
- Skip code review for AI code
|
||||
- Include sensitive data in prompts
|
||||
- Rely on AI for architectural decisions
|
||||
- Use AI-generated code you don't understand
|
||||
- Assume AI knows your business requirements
|
||||
- Let AI replace your expertise
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Understand [AI limitations](../limitations) to know when caution is needed
|
||||
- Try the [practical examples](../../getting-more) to apply these best practices
|
||||
- Explore [community resources](../../community-resources) for more tips and techniques
|
||||
|
|
@ -0,0 +1,358 @@
|
|||
---
|
||||
title: "Effective Prompting"
|
||||
linkTitle: "Effective Prompting"
|
||||
weight: 3
|
||||
description: >
|
||||
Learn how to communicate clearly with AI assistants to get the best results
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The quality of AI-generated code depends heavily on how you communicate your needs. This guide teaches you how to write effective prompts that lead to better results.
|
||||
|
||||
## The Basics of Good Prompts
|
||||
|
||||
### Be Specific
|
||||
Vague prompts lead to generic results. Provide clear, specific instructions.
|
||||
|
||||
❌ **Vague**: "Create a page"
|
||||
```
|
||||
Create a page
|
||||
```
|
||||
|
||||
✅ **Specific**: "Create a card page for Customer with fields No, Name, Address, and Phone Number"
|
||||
```
|
||||
Create a card page for the Customer table that displays these fields:
|
||||
- No.
|
||||
- Name
|
||||
- Address
|
||||
- Phone No.
|
||||
Include FactBoxes for Sales Statistics and Contact Information.
|
||||
```
|
||||
|
||||
### Provide Context
|
||||
Help the AI understand what you're working on.
|
||||
|
||||
❌ **No Context**: "Add a field"
|
||||
```
|
||||
Add a field to store email
|
||||
```
|
||||
|
||||
✅ **With Context**: "Add an email field to the Customer table extension for newsletter subscriptions"
|
||||
```
|
||||
I'm extending the Customer table. Add a new field called "Newsletter Email" to store
|
||||
the email address customers want to use for newsletters. This is separate from their
|
||||
primary email. Make it a Text field with length 80.
|
||||
```
|
||||
|
||||
### Include Examples
|
||||
Show the AI what you want by providing examples.
|
||||
|
||||
✅ **With Example**:
|
||||
```
|
||||
Create an event subscriber for OnAfterValidate on Sales Header's "Sell-to Customer No."
|
||||
field, similar to this pattern:
|
||||
|
||||
[EventSubscriber(ObjectType::Table, Database::"Sales Header", 'OnAfterValidateEvent', 'Sell-to Customer No.', false, false)]
|
||||
local procedure OnAfterValidateSellToCustomerNo(var Rec: Record "Sales Header")
|
||||
begin
|
||||
// Your implementation here
|
||||
end;
|
||||
|
||||
The subscriber should copy the Newsletter Email from the Customer to the Sales Header.
|
||||
```
|
||||
|
||||
## Prompting Patterns for AL Development
|
||||
|
||||
### 1. Code Generation
|
||||
|
||||
**Pattern**: `Create a [object type] that [does what] with [specific requirements]`
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Create a codeunit named "Sales Order Validator" that validates sales orders before posting.
|
||||
It should:
|
||||
- Check that all lines have quantities > 0
|
||||
- Verify customer credit limit is not exceeded
|
||||
- Ensure all required fields are filled
|
||||
- Return a list of validation errors
|
||||
Use AL coding best practices.
|
||||
```
|
||||
|
||||
### 2. Code Explanation
|
||||
|
||||
**Pattern**: `Explain [what] in [level of detail]`
|
||||
|
||||
**Examples**:
|
||||
```
|
||||
// Simple explanation
|
||||
Explain what this function does
|
||||
|
||||
// Detailed explanation
|
||||
Explain this procedure in detail, including the purpose of each parameter
|
||||
and the business logic flow
|
||||
|
||||
// For learning
|
||||
Explain this code as if I'm new to AL development
|
||||
```
|
||||
|
||||
### 3. Code Improvement
|
||||
|
||||
**Pattern**: `Improve this code by [what to improve]`
|
||||
|
||||
**Examples**:
|
||||
```
|
||||
Improve this code to follow AL best practices
|
||||
|
||||
Refactor this procedure to be more performant
|
||||
|
||||
Add error handling to this code
|
||||
|
||||
Make this code more testable by reducing dependencies
|
||||
```
|
||||
|
||||
### 4. Code Review
|
||||
|
||||
**Pattern**: `Review this code for [specific concerns]`
|
||||
|
||||
**Examples**:
|
||||
```
|
||||
Review this code for potential bugs and performance issues
|
||||
|
||||
Check this code against AL coding guidelines
|
||||
|
||||
Identify security concerns in this procedure
|
||||
|
||||
Find opportunities to reduce database calls in this code
|
||||
```
|
||||
|
||||
### 5. Documentation
|
||||
|
||||
**Pattern**: `Generate [documentation type] for [what]`
|
||||
|
||||
**Examples**:
|
||||
```
|
||||
Generate XML documentation comments for all procedures in this file
|
||||
|
||||
Create a README explaining what this extension does and how to install it
|
||||
|
||||
Write user documentation for this new feature
|
||||
```
|
||||
|
||||
### 6. Testing
|
||||
|
||||
**Pattern**: `Create tests for [what] that [test scenarios]`
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Create test codeunit for the Sales Order Validator that tests:
|
||||
- Valid orders pass validation
|
||||
- Orders with zero quantities fail
|
||||
- Orders exceeding credit limit fail
|
||||
- All validation error messages are correct
|
||||
Use the AL Test framework with Given-When-Then pattern.
|
||||
```
|
||||
|
||||
## Advanced Prompting Techniques
|
||||
|
||||
### Chain of Thought
|
||||
Break complex requests into steps:
|
||||
|
||||
```
|
||||
I need to create a new feature for automatic discount calculation. Let's approach this step by step:
|
||||
|
||||
1. First, create a table extension for Sales Line to store discount category
|
||||
2. Then, create a discount setup table with categories and percentages
|
||||
3. Next, create a codeunit to calculate discounts based on category
|
||||
4. Finally, add an event subscriber to apply discounts automatically
|
||||
|
||||
Let's start with step 1...
|
||||
```
|
||||
|
||||
### Constraints and Requirements
|
||||
Be explicit about what you do and don't want:
|
||||
|
||||
```
|
||||
Create a procedure to import customer data from CSV.
|
||||
Requirements:
|
||||
- Use streams for large file handling
|
||||
- Validate email format before importing
|
||||
- Skip duplicate records (based on external ID)
|
||||
- Log errors but continue processing
|
||||
- Return summary of imported, skipped, and failed records
|
||||
Do NOT:
|
||||
- Use temporary files
|
||||
- Import if any record fails validation
|
||||
- Modify existing customer records
|
||||
```
|
||||
|
||||
### Reference Standards
|
||||
Point to specific coding standards or patterns:
|
||||
|
||||
```
|
||||
Create a page extension following the AL coding standards in this repository.
|
||||
Use the same XML documentation pattern as in CustomerProcessor.codeunit.al.
|
||||
Follow the naming conventions in our README.md.
|
||||
```
|
||||
|
||||
### Iterative Refinement
|
||||
Start broad, then refine:
|
||||
|
||||
```
|
||||
// First prompt
|
||||
Create a codeunit to process sales orders
|
||||
|
||||
// After seeing initial result, refine
|
||||
Add error handling using try-catch pattern
|
||||
|
||||
// Further refinement
|
||||
Add logging using AL telemetry
|
||||
|
||||
// Final touch
|
||||
Add XML documentation comments
|
||||
```
|
||||
|
||||
## AL-Specific Prompting Tips
|
||||
|
||||
### Specify AL Version
|
||||
```
|
||||
Create an AL procedure compatible with Business Central version 21
|
||||
```
|
||||
|
||||
### Mention Dependencies
|
||||
```
|
||||
Create a page that uses the "Temp Blob" codeunit from the System Application
|
||||
```
|
||||
|
||||
### Include Object Numbers (if applicable)
|
||||
```
|
||||
Create table 50100 "Custom Discount Setup" with fields...
|
||||
```
|
||||
|
||||
### Specify Application Area
|
||||
```
|
||||
Create a page with ApplicationArea set to #Basic,#Suite
|
||||
```
|
||||
|
||||
### Reference Standard BC Objects
|
||||
```
|
||||
Create a table extension for table 18 "Customer" that adds...
|
||||
```
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### ❌ Too Vague
|
||||
```
|
||||
Make it better
|
||||
Fix this
|
||||
Create something for customers
|
||||
```
|
||||
|
||||
### ❌ Asking Multiple Unrelated Things
|
||||
```
|
||||
Create a customer page, fix the sales order bug, and document the project
|
||||
```
|
||||
*Better*: Break into separate prompts
|
||||
|
||||
### ❌ Assuming Too Much Context
|
||||
```
|
||||
Add the field we discussed
|
||||
```
|
||||
*Better*: Restate what you need
|
||||
|
||||
### ❌ No Validation Criteria
|
||||
```
|
||||
Create a validation function
|
||||
```
|
||||
*Better*: Specify what to validate and how
|
||||
|
||||
## Examples of Great Prompts
|
||||
|
||||
### Example 1: Table Extension
|
||||
```
|
||||
Create a table extension for Table 36 "Sales Header" that adds these fields:
|
||||
- "Requested Delivery Date" (Date)
|
||||
- "Special Instructions" (Text[250])
|
||||
- "Requires Approval" (Boolean)
|
||||
|
||||
Add triggers:
|
||||
- Set "Requires Approval" to true when amount exceeds $10,000
|
||||
- Validate "Requested Delivery Date" is not in the past
|
||||
|
||||
Include XML documentation for all fields.
|
||||
```
|
||||
|
||||
### Example 2: API Page
|
||||
```
|
||||
Create an API page for the Item table that exposes:
|
||||
- No.
|
||||
- Description
|
||||
- Unit Price
|
||||
- Inventory
|
||||
|
||||
Follow AL API best practices:
|
||||
- Use API versioning (v1.0)
|
||||
- Include OData annotations
|
||||
- Handle GET, POST, PATCH methods
|
||||
- Validate required fields on POST
|
||||
```
|
||||
|
||||
### Example 3: Test Code
|
||||
```
|
||||
Create a test codeunit for the "Sales Order Validator" codeunit.
|
||||
Tests needed:
|
||||
1. TestValidOrderPassesValidation - Create valid order, verify no errors
|
||||
2. TestZeroQuantityFails - Create order with 0 quantity, verify error
|
||||
3. TestCreditLimitExceeded - Create order exceeding limit, verify error
|
||||
4. TestMissingRequiredField - Skip required field, verify error
|
||||
|
||||
Use:
|
||||
- [Test] attribute
|
||||
- Given-When-Then pattern
|
||||
- LibrarySales for test data
|
||||
- Assert for verification
|
||||
```
|
||||
|
||||
## Practice Exercise
|
||||
|
||||
Try improving this vague prompt:
|
||||
|
||||
❌ **Vague**:
|
||||
```
|
||||
Create code for discounts
|
||||
```
|
||||
|
||||
✅ **Improved Version** (your attempt):
|
||||
```
|
||||
[Think about: What type of code? What discounts? What should it do?
|
||||
What are the requirements? What standards should it follow?]
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>See Suggested Answer</summary>
|
||||
|
||||
```
|
||||
Create a codeunit "Customer Discount Manager" that calculates volume-based discounts.
|
||||
|
||||
Requirements:
|
||||
- Accept parameters: Customer No., Item No., Quantity
|
||||
- Return: Discount percentage (Decimal)
|
||||
- Business logic:
|
||||
* 0-10 units: No discount
|
||||
* 11-50 units: 5% discount
|
||||
* 51-100 units: 10% discount
|
||||
* 100+ units: 15% discount
|
||||
- Read discount tiers from a setup table
|
||||
- Log calculation to telemetry
|
||||
- Include error handling for invalid inputs
|
||||
- Add XML documentation
|
||||
- Follow AL best practices for procedure naming and structure
|
||||
```
|
||||
</details>
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that you know how to write effective prompts:
|
||||
- Review the [best practices](../best-practices) for AI-assisted development
|
||||
- Try the [practical examples](../../getting-more) with your new prompting skills
|
||||
- Understand the [limitations](../limitations) of AI assistants
|
||||
213
content/docs/agentic-coding/GettingStarted/glossary.md
Normal file
213
content/docs/agentic-coding/GettingStarted/glossary.md
Normal file
|
|
@ -0,0 +1,213 @@
|
|||
---
|
||||
title: "Glossary"
|
||||
linkTitle: "Glossary"
|
||||
weight: 6
|
||||
description: >
|
||||
Common terms and concepts in AI-assisted development
|
||||
---
|
||||
|
||||
## AI & Coding Assistant Terms
|
||||
|
||||
### Agent / Agentic AI
|
||||
An AI system that can take actions autonomously, make decisions, and use tools to accomplish tasks. In coding, an agentic AI can read files, write code, run commands, and iterate on solutions without constant human intervention.
|
||||
|
||||
### AI Assistant / Coding Assistant
|
||||
Software that uses artificial intelligence to help you write code. Examples include GitHub Copilot, Claude, ChatGPT, Cursor, and Windsurf.
|
||||
|
||||
### Context
|
||||
Information the AI has access to when responding to your request. This can include:
|
||||
- Your current file and selection
|
||||
- Open files in your workspace
|
||||
- Previous conversation messages
|
||||
- Project structure and files
|
||||
- Tools and external data sources
|
||||
|
||||
**Why it matters**: The more relevant context the AI has, the better its responses. Limited context can lead to generic or incorrect suggestions.
|
||||
|
||||
### Context Window
|
||||
The maximum amount of text (measured in tokens) an AI can process at once. Think of it as the AI's "working memory."
|
||||
|
||||
**Example**: A 200K token context window can hold roughly 150,000 words of text—about 300 pages.
|
||||
|
||||
### Hallucination
|
||||
When an AI generates information that sounds plausible but is incorrect or fabricated. This can include:
|
||||
- Non-existent AL objects or methods
|
||||
- Made-up API endpoints
|
||||
- Incorrect syntax or patterns
|
||||
|
||||
**How to avoid**: Always verify AI suggestions, especially for critical code or unfamiliar APIs.
|
||||
|
||||
### Inference
|
||||
The process of an AI model generating a response to your input. Each time you send a prompt and get a response, that's one inference.
|
||||
|
||||
### Large Language Model (LLM)
|
||||
The AI technology powering coding assistants. LLMs are trained on vast amounts of text (including code) to understand and generate human-like responses.
|
||||
|
||||
**Examples**: GPT-4, Claude 3.5 Sonnet, Llama, Gemini
|
||||
|
||||
### Model
|
||||
The specific AI system you're interacting with. Different models have different capabilities, strengths, and context windows.
|
||||
|
||||
**Examples**:
|
||||
- Claude 3.5 Sonnet (good at code and reasoning)
|
||||
- GPT-4o (fast, multimodal)
|
||||
- o1 (optimized for complex reasoning)
|
||||
|
||||
---
|
||||
|
||||
## Prompting & Communication
|
||||
|
||||
### Prompt
|
||||
Your input or question to the AI. A prompt can be:
|
||||
- A question: "How do I post a sales invoice in AL?"
|
||||
- A command: "Add error handling to this function"
|
||||
- A request: "Refactor this code to use modern AL patterns"
|
||||
|
||||
**Tip**: Clear, specific prompts get better results than vague ones.
|
||||
|
||||
### System Prompt / Instructions
|
||||
Background instructions that guide the AI's behavior and personality. You typically don't see these, but they tell the AI how to respond (e.g., "You are a Business Central expert," "Be concise," "Provide code examples").
|
||||
|
||||
### Few-Shot / One-Shot Prompting
|
||||
Providing examples in your prompt to guide the AI's response format.
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Create getter methods like this example:
|
||||
procedure GetCustomerName(): Text[100]
|
||||
begin
|
||||
exit("Customer Name");
|
||||
end
|
||||
|
||||
Now create a getter for "Customer Email"
|
||||
```
|
||||
|
||||
### Chain of Thought
|
||||
Asking the AI to explain its reasoning step-by-step before providing an answer. This often improves accuracy for complex problems.
|
||||
|
||||
**Example**: "Let's think through how to design this posting routine step by step..."
|
||||
|
||||
---
|
||||
|
||||
## Technical Terms
|
||||
|
||||
### Token
|
||||
The basic unit of text that AI models process. Roughly:
|
||||
- 1 token ≈ 4 characters in English
|
||||
- 1 token ≈ ¾ of a word
|
||||
- 100 tokens ≈ 75 words
|
||||
|
||||
**Why it matters**: Context windows, pricing, and API limits are measured in tokens.
|
||||
|
||||
### Tool / Tool Calling / Function Calling
|
||||
External capabilities the AI can use to perform actions beyond text generation:
|
||||
- Read and write files
|
||||
- Run terminal commands
|
||||
- Search the web
|
||||
- Query databases
|
||||
- Execute MCP server tools
|
||||
|
||||
**Example**: When you ask "What's in my app.json?", the AI uses a "read file" tool rather than guessing.
|
||||
|
||||
### MCP (Model Context Protocol)
|
||||
An open standard for connecting AI assistants to external tools and data sources. MCP servers expose capabilities (like AL symbol databases, Azure DevOps, time tracking) that AI assistants can use.
|
||||
|
||||
**Example**: The AL Dependency MCP Server lets your AI assistant search compiled AL packages.
|
||||
|
||||
### RAG (Retrieval-Augmented Generation)
|
||||
A technique where the AI retrieves relevant information from external sources before generating a response. This helps provide accurate, up-to-date information beyond the AI's training data.
|
||||
|
||||
**Example**: BC Code Intelligence MCP uses RAG to fetch specific Business Central knowledge topics.
|
||||
|
||||
### Temperature
|
||||
A setting that controls how creative or deterministic the AI's responses are:
|
||||
- **Low temperature (0.0-0.3)**: Focused, consistent, predictable—good for code generation
|
||||
- **High temperature (0.7-1.0)**: Creative, varied, exploratory—good for brainstorming
|
||||
|
||||
### Embeddings
|
||||
Mathematical representations of text that capture semantic meaning. Used to find relevant information by similarity rather than exact keyword matches.
|
||||
|
||||
**Example**: Searching for "customer posting" would find content about "posting customer transactions" even without exact word matches.
|
||||
|
||||
---
|
||||
|
||||
## AL & Business Central Specific
|
||||
|
||||
### AL Language Server
|
||||
A background service that provides intelligent code features for AL:
|
||||
- Code completion
|
||||
- Go to definition
|
||||
- Find references
|
||||
- Syntax checking
|
||||
|
||||
**Note**: Some MCP servers (like Serena) integrate with the AL Language Server to give AI assistants these capabilities.
|
||||
|
||||
### Symbol
|
||||
In AL, a symbol is any named code element:
|
||||
- Objects (tables, pages, codeunits)
|
||||
- Fields
|
||||
- Procedures
|
||||
- Variables
|
||||
|
||||
### .app Package
|
||||
A compiled AL extension package containing symbols and metadata. AI assistants can't read these directly, which is why tools like AL Dependency MCP Server exist.
|
||||
|
||||
### Object ID
|
||||
The numeric identifier for AL objects (tables, pages, codeunits, etc.). Managing these IDs across teams requires coordination to avoid conflicts—that's where AL Object ID Ninja MCP helps.
|
||||
|
||||
---
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Pair Programming
|
||||
A development practice where two people work together on the same code. With AI assistants, you're essentially pair programming with an AI partner.
|
||||
|
||||
### Code Review
|
||||
Examining code to find issues, ensure quality, and share knowledge. AI assistants can help with code review by analyzing patterns, suggesting improvements, and catching common mistakes.
|
||||
|
||||
### Refactoring
|
||||
Improving code structure and readability without changing its behavior. AI assistants excel at refactoring tasks like renaming, extracting methods, and modernizing patterns.
|
||||
|
||||
### Test-Driven Development (TDD)
|
||||
Writing tests before writing the code that satisfies them. AI assistants can help generate test cases and implementations.
|
||||
|
||||
---
|
||||
|
||||
## Common Acronyms
|
||||
|
||||
| Term | Meaning |
|
||||
|------|---------|
|
||||
| **AI** | Artificial Intelligence |
|
||||
| **LLM** | Large Language Model |
|
||||
| **MCP** | Model Context Protocol |
|
||||
| **NLP** | Natural Language Processing |
|
||||
| **RAG** | Retrieval-Augmented Generation |
|
||||
| **TDD** | Test-Driven Development |
|
||||
| **LSP** | Language Server Protocol |
|
||||
| **IDE** | Integrated Development Environment |
|
||||
| **API** | Application Programming Interface |
|
||||
| **CRUD** | Create, Read, Update, Delete |
|
||||
| **CLI** | Command Line Interface |
|
||||
| **PAT** | Personal Access Token |
|
||||
|
||||
---
|
||||
|
||||
## Tips for Learning the Language
|
||||
|
||||
**Don't worry about knowing everything!** Start with these core concepts:
|
||||
- **Prompt**: What you say to the AI
|
||||
- **Context**: What information the AI can see
|
||||
- **Token**: How AI text is measured
|
||||
- **Hallucination**: When AI makes things up
|
||||
- **Tool**: Actions the AI can take (like reading files)
|
||||
|
||||
As you work with AI assistants, you'll naturally pick up more terminology. The important thing is understanding how to communicate effectively and knowing when to verify AI suggestions.
|
||||
|
||||
---
|
||||
|
||||
## Related Resources
|
||||
|
||||
- **[What is Agentic Coding](../what-is-agentic-coding)** - Core concepts explained
|
||||
- **[Effective Prompting](../effective-prompting)** - How to communicate with AI
|
||||
- **[Understanding Limitations](../limitations)** - What AI can and can't do
|
||||
- **[Tools & MCP Servers](../../communityresources/tools)** - Extending AI capabilities
|
||||
473
content/docs/agentic-coding/GettingStarted/limitations.md
Normal file
473
content/docs/agentic-coding/GettingStarted/limitations.md
Normal file
|
|
@ -0,0 +1,473 @@
|
|||
---
|
||||
title: "Understanding Limitations"
|
||||
linkTitle: "Limitations"
|
||||
weight: 5
|
||||
description: >
|
||||
Know when to use (and not use) AI assistance in AL development
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
AI coding assistants are powerful tools, but they have limitations. Understanding these limitations helps you use AI effectively and avoid common pitfalls.
|
||||
|
||||
## Knowledge Limitations
|
||||
|
||||
### Training Data Cutoff
|
||||
AI models are trained on data up to a specific date:
|
||||
|
||||
**Implication**:
|
||||
- May not know about the latest AL features
|
||||
- Might suggest deprecated APIs
|
||||
- Could miss recent Business Central updates
|
||||
- May not be aware of new best practices
|
||||
|
||||
**What to Do**:
|
||||
- Verify suggestions against current documentation
|
||||
- Check for deprecated features
|
||||
- Stay updated on BC releases yourself
|
||||
- Supplement AI with official Microsoft docs
|
||||
|
||||
### Lack of Real-Time Information
|
||||
AI doesn't know:
|
||||
- Your specific BC version and configuration
|
||||
- Your organization's custom extensions
|
||||
- Your specific business requirements
|
||||
- Current state of your codebase
|
||||
|
||||
**What to Do**:
|
||||
- Provide context in your prompts
|
||||
- Specify BC version when relevant
|
||||
- Describe dependencies and extensions
|
||||
- Share organizational standards
|
||||
|
||||
### Incomplete AL Knowledge
|
||||
AI might not fully understand:
|
||||
- Complex AL compiler behavior
|
||||
- Subtle differences between AL versions
|
||||
- Specific BC platform limitations
|
||||
- Performance characteristics of certain operations
|
||||
|
||||
**What to Do**:
|
||||
- Test generated code thoroughly
|
||||
- Verify with official documentation
|
||||
- Profile performance-critical code
|
||||
- Consult AL experts for complex scenarios
|
||||
|
||||
## Code Quality Limitations
|
||||
|
||||
### May Generate Suboptimal Code
|
||||
|
||||
**Example 1: Inefficient Database Access**
|
||||
```al
|
||||
// AI might generate:
|
||||
procedure CountCustomersInCity(CityName: Text): Integer
|
||||
var
|
||||
Customer: Record Customer;
|
||||
Counter: Integer;
|
||||
begin
|
||||
Counter := 0;
|
||||
if Customer.FindSet() then
|
||||
repeat
|
||||
if Customer.City = CityName then
|
||||
Counter += 1;
|
||||
until Customer.Next() = 0;
|
||||
exit(Counter);
|
||||
end;
|
||||
|
||||
// Better approach:
|
||||
procedure CountCustomersInCity(CityName: Text): Integer
|
||||
var
|
||||
Customer: Record Customer;
|
||||
begin
|
||||
Customer.SetRange(City, CityName);
|
||||
exit(Customer.Count);
|
||||
end;
|
||||
```
|
||||
|
||||
**Example 2: Missing Error Handling**
|
||||
```al
|
||||
// AI might generate:
|
||||
procedure GetCustomerEmail(CustomerNo: Code[20]): Text
|
||||
var
|
||||
Customer: Record Customer;
|
||||
begin
|
||||
Customer.Get(CustomerNo);
|
||||
exit(Customer."E-Mail");
|
||||
end;
|
||||
|
||||
// Should include error handling:
|
||||
procedure GetCustomerEmail(CustomerNo: Code[20]): Text
|
||||
var
|
||||
Customer: Record Customer;
|
||||
begin
|
||||
if not Customer.Get(CustomerNo) then
|
||||
Error('Customer %1 does not exist.', CustomerNo);
|
||||
|
||||
if Customer."E-Mail" = '' then
|
||||
Error('Customer %1 has no email address.', CustomerNo);
|
||||
|
||||
exit(Customer."E-Mail");
|
||||
end;
|
||||
```
|
||||
|
||||
### May Not Follow Your Standards
|
||||
AI doesn't automatically know:
|
||||
- Your naming conventions
|
||||
- Your code organization preferences
|
||||
- Your error handling patterns
|
||||
- Your logging standards
|
||||
|
||||
**What to Do**:
|
||||
- Include standards in prompts
|
||||
- Create prompt templates
|
||||
- Maintain coding guidelines document
|
||||
- Review and adapt generated code
|
||||
|
||||
### May Create Inconsistent Code
|
||||
AI might:
|
||||
- Use different patterns across files
|
||||
- Mix coding styles
|
||||
- Apply inconsistent naming
|
||||
- Vary error handling approaches
|
||||
|
||||
**What to Do**:
|
||||
- Establish clear patterns early
|
||||
- Refactor for consistency
|
||||
- Use linters and code analyzers
|
||||
- Conduct thorough code reviews
|
||||
|
||||
## Business Logic Limitations
|
||||
|
||||
### No Domain Knowledge
|
||||
AI doesn't understand:
|
||||
- Your specific business processes
|
||||
- Industry regulations you must follow
|
||||
- Your customers' needs
|
||||
- Your company's policies
|
||||
|
||||
**Example**:
|
||||
```
|
||||
You ask: "Create discount calculation logic"
|
||||
|
||||
AI generates: 10% flat discount
|
||||
|
||||
But you need:
|
||||
- Tiered discounts by volume
|
||||
- Special rates for preferred customers
|
||||
- Regional pricing variations
|
||||
- Promotional discounts
|
||||
- Loyalty program integration
|
||||
```
|
||||
|
||||
**What to Do**:
|
||||
- Provide detailed business requirements
|
||||
- Include business rules in prompts
|
||||
- Review logic for business correctness
|
||||
- Validate with business stakeholders
|
||||
|
||||
### Can't Make Business Decisions
|
||||
AI shouldn't decide:
|
||||
- Which features to implement
|
||||
- How to prioritize requirements
|
||||
- What trade-offs to make
|
||||
- Which approach best fits your needs
|
||||
|
||||
**You must decide**:
|
||||
- Architecture and design
|
||||
- Feature scope
|
||||
- Performance vs. complexity trade-offs
|
||||
- User experience choices
|
||||
|
||||
## Technical Limitations
|
||||
|
||||
### Context Window Limitations
|
||||
AI can only see:
|
||||
- A limited amount of code at once
|
||||
- Recently opened files
|
||||
- Content you explicitly share
|
||||
|
||||
**Implications**:
|
||||
- Might miss dependencies in other files
|
||||
- May not see full context of large codebases
|
||||
- Could suggest code that conflicts with other parts
|
||||
|
||||
**What to Do**:
|
||||
- Keep related files open
|
||||
- Provide context in prompts
|
||||
- Reference specific files and procedures
|
||||
- Review for integration issues
|
||||
|
||||
### Can't Execute or Test Code
|
||||
AI can't:
|
||||
- Run your code
|
||||
- Execute tests
|
||||
- Connect to your database
|
||||
- Verify actual behavior
|
||||
|
||||
**Implications**:
|
||||
- Might generate syntactically correct but broken code
|
||||
- Can't verify business logic works
|
||||
- Won't catch runtime errors
|
||||
- Can't validate performance
|
||||
|
||||
**What to Do**:
|
||||
- Always test generated code
|
||||
- Run your test suite
|
||||
- Verify in actual BC environment
|
||||
- Profile performance-critical code
|
||||
|
||||
### Can't Access External Systems
|
||||
AI doesn't know about:
|
||||
- Your database state
|
||||
- External APIs you integrate with
|
||||
- Third-party extensions installed
|
||||
- Network or security constraints
|
||||
|
||||
**What to Do**:
|
||||
- Document external dependencies
|
||||
- Test integrations thoroughly
|
||||
- Verify API compatibility
|
||||
- Check security implications
|
||||
|
||||
## Safety and Security Limitations
|
||||
|
||||
### Limited Security Awareness
|
||||
AI might not catch:
|
||||
- SQL injection vulnerabilities
|
||||
- Authorization bypass issues
|
||||
- Data leakage risks
|
||||
- Insecure data handling
|
||||
|
||||
**Example**:
|
||||
```al
|
||||
// AI might generate:
|
||||
procedure RunDynamicQuery(FilterText: Text)
|
||||
begin
|
||||
// Could be SQL injection risk if FilterText comes from user
|
||||
Customer.SetFilter(City, FilterText);
|
||||
end;
|
||||
|
||||
// Need to add validation:
|
||||
procedure RunDynamicQuery(FilterText: Text)
|
||||
begin
|
||||
ValidateFilterInput(FilterText); // Add validation
|
||||
Customer.SetFilter(City, FilterText);
|
||||
end;
|
||||
```
|
||||
|
||||
**What to Do**:
|
||||
- Security review all generated code
|
||||
- Validate inputs from users
|
||||
- Follow security best practices
|
||||
- Consult security experts
|
||||
|
||||
### Privacy Concerns
|
||||
Be careful not to share:
|
||||
- Customer data
|
||||
- Production database content
|
||||
- API keys or credentials
|
||||
- Proprietary business logic
|
||||
|
||||
**What to Do**:
|
||||
- Use sample data in prompts
|
||||
- Sanitize code before sharing
|
||||
- Review organizational policies
|
||||
- Use private AI instances if available
|
||||
|
||||
## Reliability Limitations
|
||||
|
||||
### Inconsistent Results
|
||||
AI might:
|
||||
- Give different answers to same question
|
||||
- Vary quality across generations
|
||||
- Make occasional "hallucinations"
|
||||
- Provide confident but wrong information
|
||||
|
||||
**What to Do**:
|
||||
- Verify all suggestions
|
||||
- Don't assume correctness
|
||||
- Cross-check with documentation
|
||||
- Regenerate if quality is poor
|
||||
|
||||
### Can Make Mistakes
|
||||
AI can:
|
||||
- Misunderstand requirements
|
||||
- Make logical errors
|
||||
- Suggest deprecated features
|
||||
- Create subtle bugs
|
||||
|
||||
**Real Examples**:
|
||||
```al
|
||||
// AI might confuse similar concepts:
|
||||
// You ask for "customer balance"
|
||||
// It generates code for "customer credit limit"
|
||||
|
||||
// AI might mix AL versions:
|
||||
// Suggest AL syntax not available in your BC version
|
||||
|
||||
// AI might misapply patterns:
|
||||
// Use patterns from C# instead of AL conventions
|
||||
```
|
||||
|
||||
**What to Do**:
|
||||
- Treat AI as a junior developer
|
||||
- Review everything carefully
|
||||
- Test thoroughly
|
||||
- Validate assumptions
|
||||
|
||||
## Workflow Limitations
|
||||
|
||||
### Can't Handle Complex Refactoring
|
||||
AI struggles with:
|
||||
- Large-scale architecture changes
|
||||
- Multi-file refactoring
|
||||
- Complex dependency updates
|
||||
- Breaking changes across modules
|
||||
|
||||
**What to Do**:
|
||||
- Break into smaller steps
|
||||
- Do complex refactoring manually
|
||||
- Use AI for individual pieces
|
||||
- Plan architecture yourself
|
||||
|
||||
### Limited Long-Term Memory
|
||||
AI doesn't remember:
|
||||
- Previous conversations (in some tools)
|
||||
- Decisions made earlier in project
|
||||
- Your preferences over time
|
||||
- Context from last week
|
||||
|
||||
**What to Do**:
|
||||
- Restate context when needed
|
||||
- Document decisions
|
||||
- Include relevant background in prompts
|
||||
- Don't assume AI remembers
|
||||
|
||||
### Can't Collaborate Directly
|
||||
AI can't:
|
||||
- Participate in code reviews
|
||||
- Attend planning meetings
|
||||
- Discuss with stakeholders
|
||||
- Make consensus decisions
|
||||
|
||||
**What to Do**:
|
||||
- Use AI for preparation
|
||||
- Review AI suggestions with team
|
||||
- Make collaborative decisions yourself
|
||||
- Document team agreements
|
||||
|
||||
## When to Be Extra Careful
|
||||
|
||||
### High-Risk Scenarios
|
||||
|
||||
**Financial Calculations**
|
||||
```
|
||||
Extra vigilance needed for:
|
||||
- Payment processing
|
||||
- Tax calculations
|
||||
- Currency conversions
|
||||
- Pricing logic
|
||||
```
|
||||
|
||||
**Compliance and Audit**
|
||||
```
|
||||
Careful review for:
|
||||
- Regulatory compliance code
|
||||
- Audit trail functionality
|
||||
- Data retention policies
|
||||
- Access control
|
||||
```
|
||||
|
||||
**Data Integrity**
|
||||
```
|
||||
Thorough testing for:
|
||||
- Database modifications
|
||||
- Data migrations
|
||||
- Batch processing
|
||||
- Transaction handling
|
||||
```
|
||||
|
||||
**Integration Points**
|
||||
```
|
||||
Extensive validation for:
|
||||
- API integrations
|
||||
- Web service calls
|
||||
- External system connections
|
||||
- Data synchronization
|
||||
```
|
||||
|
||||
## Recognizing AI Limitations
|
||||
|
||||
### Warning Signs
|
||||
|
||||
**The AI:**
|
||||
- Gives very generic solutions
|
||||
- Doesn't ask clarifying questions
|
||||
- Suggests deprecated features
|
||||
- Provides inconsistent answers
|
||||
- Seems overly confident about uncertain things
|
||||
- Generates syntactically correct but illogical code
|
||||
|
||||
**What to Do:**
|
||||
- Seek second opinion
|
||||
- Consult documentation
|
||||
- Ask a colleague
|
||||
- Test more thoroughly
|
||||
- Provide more context
|
||||
- Try rephrasing prompt
|
||||
|
||||
## Complementing AI with Other Resources
|
||||
|
||||
### Use Multiple Sources
|
||||
|
||||
**For Learning:**
|
||||
- Official Microsoft Learn
|
||||
- BC documentation
|
||||
- Community blogs
|
||||
- Training courses
|
||||
|
||||
**For Problem Solving:**
|
||||
- Microsoft Docs
|
||||
- Community forums
|
||||
- Stack Overflow
|
||||
- Colleague expertise
|
||||
|
||||
**For Best Practices:**
|
||||
- AL Guidelines (this site!)
|
||||
- Microsoft patterns
|
||||
- Community standards
|
||||
- Team conventions
|
||||
|
||||
**For Validation:**
|
||||
- Code analyzers
|
||||
- Test frameworks
|
||||
- Peer review
|
||||
- Static analysis tools
|
||||
|
||||
## The Bottom Line
|
||||
|
||||
### AI is a Tool, Not a Solution
|
||||
- Use it to augment your skills
|
||||
- Don't rely on it exclusively
|
||||
- Maintain your expertise
|
||||
- Stay critical and thoughtful
|
||||
|
||||
### Your Responsibilities Remain
|
||||
- Understand the code
|
||||
- Ensure correctness
|
||||
- Maintain quality
|
||||
- Make decisions
|
||||
- Own the results
|
||||
|
||||
### Continuous Learning
|
||||
- AI tools will improve
|
||||
- Your skills must keep pace
|
||||
- Learn from AI's mistakes
|
||||
- Evolve your practices
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that you understand AI limitations:
|
||||
- Apply this knowledge in the [practical examples](../../getting-more)
|
||||
- See how to work within these limitations in [best practices](../best-practices)
|
||||
- Explore [community resources](../../community-resources) for more insights
|
||||
226
content/docs/agentic-coding/GettingStarted/setup.md
Normal file
226
content/docs/agentic-coding/GettingStarted/setup.md
Normal file
|
|
@ -0,0 +1,226 @@
|
|||
---
|
||||
title: "Setting Up Your Environment"
|
||||
linkTitle: "Setup"
|
||||
weight: 2
|
||||
description: >
|
||||
Configure your development environment for optimal AI-assisted AL development
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
To get the most out of AI-powered coding assistance for AL development, you'll need to set up your environment properly. This guide covers the essential tools and configurations.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Required
|
||||
- **Visual Studio Code**: The primary IDE for AL development
|
||||
- **AL Language Extension**: Microsoft's official AL extension for VS Code
|
||||
- **AI Coding Assistant**: One of the following:
|
||||
- GitHub Copilot
|
||||
- GitHub Copilot Chat
|
||||
- Other compatible AI assistants
|
||||
|
||||
### Recommended
|
||||
- **Git**: For version control and change tracking
|
||||
- **AL Test Runner**: For running and managing tests
|
||||
- **Business Central Docker Container**: For local development and testing
|
||||
|
||||
## Installing GitHub Copilot
|
||||
|
||||
GitHub Copilot is one of the most popular AI assistants for coding:
|
||||
|
||||
1. **Sign up for GitHub Copilot**
|
||||
- Visit [GitHub Copilot](https://github.com/features/copilot)
|
||||
- Choose a subscription plan (free trial available)
|
||||
|
||||
2. **Install the VS Code Extension**
|
||||
- Open VS Code
|
||||
- Go to Extensions (Ctrl+Shift+X)
|
||||
- Search for "GitHub Copilot"
|
||||
- Install both:
|
||||
- GitHub Copilot
|
||||
- GitHub Copilot Chat
|
||||
|
||||
3. **Sign In**
|
||||
- Click "Sign in to GitHub" when prompted
|
||||
- Authorize the extension
|
||||
|
||||
## Configuring VS Code for AL + AI
|
||||
|
||||
### Workspace Settings
|
||||
|
||||
Add these settings to your workspace `.vscode/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
// AL Language settings
|
||||
"al.enableCodeAnalysis": true,
|
||||
"al.codeAnalyzers": ["${CodeCop}", "${PerTenantExtensionCop}", "${UICop}"],
|
||||
|
||||
// GitHub Copilot settings
|
||||
"github.copilot.enable": {
|
||||
"*": true,
|
||||
"al": true
|
||||
},
|
||||
|
||||
// Editor settings for better AI integration
|
||||
"editor.inlineSuggest.enabled": true,
|
||||
"editor.quickSuggestions": {
|
||||
"other": true,
|
||||
"comments": true,
|
||||
"strings": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### AL Project Structure
|
||||
|
||||
Organize your AL project for better AI context:
|
||||
|
||||
```
|
||||
MyExtension/
|
||||
├── .vscode/
|
||||
│ ├── settings.json
|
||||
│ └── launch.json
|
||||
├── src/
|
||||
│ ├── Tables/
|
||||
│ ├── Pages/
|
||||
│ ├── Codeunits/
|
||||
│ ├── Reports/
|
||||
│ └── ...
|
||||
├── test/
|
||||
│ └── ...
|
||||
├── app.json
|
||||
└── README.md
|
||||
```
|
||||
|
||||
Clear folder organization helps AI assistants understand your project structure and provide more relevant suggestions.
|
||||
|
||||
## Optimizing Context for AI
|
||||
|
||||
AI assistants work better when they have good context. Here's how to provide it:
|
||||
|
||||
### 1. Use Descriptive File Names
|
||||
```
|
||||
❌ Page1.al
|
||||
✅ CustomerListPage.al
|
||||
|
||||
❌ Cod50100.al
|
||||
✅ SalesOrderProcessor.codeunit.al
|
||||
```
|
||||
|
||||
### 2. Maintain a Good README
|
||||
Create a `README.md` in your project root with:
|
||||
- Project purpose and overview
|
||||
- Key features and functionality
|
||||
- Naming conventions
|
||||
- Architecture decisions
|
||||
|
||||
### 3. Use XML Documentation
|
||||
Document your procedures and functions:
|
||||
```al
|
||||
/// <summary>
|
||||
/// Calculates the total amount for a sales order including tax
|
||||
/// </summary>
|
||||
/// <param name="SalesHeader">The sales header record</param>
|
||||
/// <returns>The total amount including tax</returns>
|
||||
procedure CalculateTotalWithTax(var SalesHeader: Record "Sales Header"): Decimal
|
||||
```
|
||||
|
||||
### 4. Keep Related Code Together
|
||||
Place related functionality in the same files or nearby files. AI assistants can see open files and nearby code.
|
||||
|
||||
## Testing Your Setup
|
||||
|
||||
To verify everything is working:
|
||||
|
||||
1. **Open an AL file** in your project
|
||||
2. **Start typing** a procedure declaration
|
||||
3. **Check for suggestions** - You should see inline suggestions appear
|
||||
4. **Open Copilot Chat** (if using GitHub Copilot)
|
||||
- Press Ctrl+Shift+I (or Cmd+Shift+I on Mac)
|
||||
- Try asking: "Explain this AL code"
|
||||
|
||||
## Recommended Extensions
|
||||
|
||||
Install these VS Code extensions to complement your AI assistant:
|
||||
|
||||
- **AL Language**: Microsoft's official AL extension (required)
|
||||
- **AL Object Designer**: Navigate AL objects easily
|
||||
- **AL Code Outline**: View code structure
|
||||
- **AL Test Runner**: Run and manage AL tests
|
||||
- **AL Variable Helper**: Manage variable declarations
|
||||
- **GitLens**: Enhanced git integration
|
||||
|
||||
## Workspace Best Practices
|
||||
|
||||
### Open Relevant Files
|
||||
- Keep related files open in tabs
|
||||
- AI assistants can use open files for context
|
||||
|
||||
### Use Multi-Root Workspaces (When Appropriate)
|
||||
If you have dependencies or multiple related projects:
|
||||
```json
|
||||
{
|
||||
"folders": [
|
||||
{ "path": "./MyMainExtension" },
|
||||
{ "path": "./MyDependencyExtension" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Organize by Feature
|
||||
Consider organizing code by business feature rather than object type for complex projects:
|
||||
```
|
||||
src/
|
||||
├── SalesOrderProcessing/
|
||||
│ ├── SalesOrder.table.al
|
||||
│ ├── SalesOrderPage.page.al
|
||||
│ ├── SalesOrderProcessor.codeunit.al
|
||||
├── CustomerManagement/
|
||||
│ └── ...
|
||||
```
|
||||
|
||||
## Security and Privacy Considerations
|
||||
|
||||
### What Gets Sent to AI Services
|
||||
- Code snippets from your workspace
|
||||
- Currently open files
|
||||
- Your prompts and questions
|
||||
|
||||
### What You Should NOT Include
|
||||
- Sensitive credentials or passwords
|
||||
- Customer data
|
||||
- Proprietary business logic (if restricted)
|
||||
|
||||
### Best Practices
|
||||
- Review your organization's AI usage policy
|
||||
- Use `.gitignore` and `.copilotignore` files appropriately
|
||||
- Be mindful of what code is in your workspace
|
||||
- Consider using GitHub Copilot for Business for enterprise controls
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### AI Suggestions Not Appearing
|
||||
- Verify the AI extension is installed and enabled
|
||||
- Check you're signed in to your AI service
|
||||
- Ensure `editor.inlineSuggest.enabled` is true
|
||||
- Restart VS Code
|
||||
|
||||
### Poor Quality Suggestions
|
||||
- Improve code context (better file names, comments)
|
||||
- Open related files for more context
|
||||
- Use more descriptive variable and function names
|
||||
- Add XML documentation comments
|
||||
|
||||
### Performance Issues
|
||||
- Close unnecessary tabs/files
|
||||
- Disable AI for specific file types if needed
|
||||
- Check your system resources
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that your environment is set up:
|
||||
- Learn [effective prompting techniques](../effective-prompting)
|
||||
- Review [best practices](../best-practices) for AI-assisted development
|
||||
- Try the [practical examples](../../getting-more) to see AI assistance in action
|
||||
|
|
@ -0,0 +1,128 @@
|
|||
---
|
||||
title: "What is Agentic Coding?"
|
||||
linkTitle: "What is Agentic Coding"
|
||||
weight: 1
|
||||
description: >
|
||||
Understanding AI-powered coding assistance and how it transforms development
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
**Agentic coding** is a development approach where you work collaboratively with AI-powered assistants (agents) that can understand context, generate code, provide suggestions, and help maintain your codebase. Unlike simple code completion tools, these agents can:
|
||||
|
||||
- Understand natural language instructions
|
||||
- Analyze existing code and context
|
||||
- Generate complete implementations
|
||||
- Refactor and improve code
|
||||
- Explain complex code segments
|
||||
- Assist with debugging and problem-solving
|
||||
|
||||
## How It Works
|
||||
|
||||
AI coding assistants work by:
|
||||
|
||||
1. **Understanding Context**: The agent analyzes your workspace, open files, and the surrounding code to understand what you're working on
|
||||
2. **Processing Instructions**: You provide instructions in natural language (or through inline comments)
|
||||
3. **Generating Solutions**: The agent creates code, documentation, or suggestions based on your needs
|
||||
4. **Iterative Refinement**: You review, provide feedback, and the agent adjusts the output
|
||||
|
||||
## Key Capabilities for AL Development
|
||||
|
||||
### Code Generation
|
||||
Generate AL code from natural language descriptions:
|
||||
- Complete procedures and functions
|
||||
- Table extensions and page extensions
|
||||
- API pages and queries
|
||||
- Event subscribers
|
||||
- Test code
|
||||
|
||||
### Code Understanding
|
||||
Get help understanding existing code:
|
||||
- Explanations of complex logic
|
||||
- Documentation of dependencies
|
||||
- Impact analysis of changes
|
||||
|
||||
### Code Improvement
|
||||
Enhance existing code:
|
||||
- Refactoring for better performance
|
||||
- Applying AL best practices
|
||||
- Modernizing legacy code
|
||||
- Adding error handling
|
||||
|
||||
### Documentation
|
||||
Automatically create and maintain:
|
||||
- XML documentation comments
|
||||
- README files
|
||||
- API documentation
|
||||
- Code comments
|
||||
|
||||
## Benefits for AL Developers
|
||||
|
||||
### Faster Development
|
||||
- Quickly scaffold new objects and extensions
|
||||
- Implement common patterns without repetitive typing
|
||||
- Generate boilerplate code instantly
|
||||
|
||||
### Higher Quality
|
||||
- Consistent application of best practices
|
||||
- Fewer common mistakes
|
||||
- Better code organization
|
||||
|
||||
### Learning Accelerator
|
||||
- Learn AL patterns through examples
|
||||
- Understand Business Central APIs
|
||||
- Discover best practices in context
|
||||
|
||||
### Reduced Cognitive Load
|
||||
- Focus on business logic, not syntax
|
||||
- Less context switching for documentation lookups
|
||||
- Automated handling of repetitive tasks
|
||||
|
||||
## The Human-AI Partnership
|
||||
|
||||
It's important to understand that agentic coding is a **collaborative** approach:
|
||||
|
||||
### You Bring:
|
||||
- **Domain Knowledge**: Understanding of business requirements and Business Central functionality
|
||||
- **Decision Making**: Architectural choices and business logic decisions
|
||||
- **Quality Control**: Review and validation of generated code
|
||||
- **Context**: Specific requirements, constraints, and organizational standards
|
||||
|
||||
### The AI Brings:
|
||||
- **Speed**: Rapid code generation and transformation
|
||||
- **Consistency**: Adherence to patterns and best practices
|
||||
- **Breadth**: Knowledge of many AL patterns and APIs
|
||||
- **Assistance**: Help with routine tasks and documentation
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### Daily Development
|
||||
- Creating new tables, pages, and codeunits
|
||||
- Implementing event subscribers
|
||||
- Writing test code
|
||||
- Adding XML documentation
|
||||
|
||||
### Code Maintenance
|
||||
- Refactoring existing code
|
||||
- Adding telemetry to extensions
|
||||
- Improving error handling
|
||||
- Updating deprecated APIs
|
||||
|
||||
### Code Review
|
||||
- Identifying potential issues
|
||||
- Suggesting improvements
|
||||
- Checking adherence to standards
|
||||
- Finding security concerns
|
||||
|
||||
### Documentation
|
||||
- Generating README files
|
||||
- Creating API documentation
|
||||
- Writing user guides
|
||||
- Documenting complex algorithms
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that you understand what agentic coding is, learn how to:
|
||||
- [Set up your environment](../setup) for AI assistance
|
||||
- [Write effective prompts](../effective-prompting) to get better results
|
||||
- Follow [best practices](../best-practices) for AI-assisted development
|
||||
Loading…
Add table
Add a link
Reference in a new issue