⚠️

Implementation Considerations

Security, maintenance, and quality factors for creating and consuming ai-guide.md specifications

← Back to Specification

Security Considerations

Critical Warning

ai-guide.md files can expose security vulnerabilities if not carefully written. These specifications provide a roadmap readable by both helpful agents and malicious actors.

What NOT to Include

Security-Conscious Documentation

Authentication Requirements

Be explicit about required authentication without documenting bypass methods.

## Prerequisites
- Auth: Bearer token in Authorization header
- Get token: POST /auth/login
- Token expires: 1 hour

Rate Limiting (General)

Acknowledge rate limits without providing exact thresholds for abuse.

## Known Issues
- Rate limits apply to all endpoints
- Implement exponential backoff
- Monitor 429 responses

Authorization Levels

Make permission requirements clear from the start.

## Action Reference
- Admin only: /admin/* endpoints
- User must own resource: /users/{id}/edit
- Public: /products (read-only)

Security Review Checklist

  • ☐ Have you removed all credentials and secrets?
  • ☐ Could this guide help someone bypass authentication?
  • ☐ Are privileged operations clearly marked as requiring authorization?
  • ☐ Has your security team reviewed this before publishing?
  • ☐ Does this expose any internal architecture unnecessarily?
  • ☐ Could the "Known Issues" section be misinterpreted as attack vectors?
  • ☐ Are rate limits and abuse prevention measures mentioned?
  • ☐ Is this file appropriate for your threat model?

Documentation Practices

Avoid: "Need to bypass rate limiting? Add X-Internal-Request: true header"

Prefer: "Rate limits apply to all requests. Contact support for higher limits."

Maintenance and Updates

Maintenance Requirements

ai-guide.md requires ongoing maintenance. Outdated specifications cause AI agents to use incorrect information, potentially breaking implementations. An outdated guide can be more harmful than no guide at all.

Operational Risk

Outdated ai-guide.md specifications can cause agents to make requests to deprecated endpoints, use incorrect parameters, or violate updated security policies. This may result in production incidents.

Update Requirements

Mandatory Updates

Optional Updates

Automation Approaches

Test-Driven Generation

Extract ai-guide.md from integration tests. When tests pass, guide remains current.

# Generate from test suite
npm run test:generate-guide

CI/CD Validation

Add checks to ensure examples in ai-guide.md remain functional.

# Fail build if guide is stale
./scripts/validate-ai-guide.sh

Version Tracking

Include last-updated date and compatible API versions.

# ai-guide.md v1.2.0
Last-Updated: 2025-11-04
Compatible-With: [email protected]

Maintenance Checklist

  • ☐ Include ai-guide.md in documentation review process
  • ☐ Assign ownership (who maintains updates?)
  • ☐ Configure alerts for API changes
  • ☐ Test examples quarterly
  • ☐ Review issue trackers and support tickets for new known issues
  • ☐ Include updates in release checklists
  • ☐ Monitor agent error rates to detect stale information

Recommendation

Maintain a changelog at the end of your ai-guide.md file. This helps both humans and agents understand what changed and when.

Versioning Strategy

Rationale for Versioning

Without versioning, AI agents cannot determine whether information is current. Consequences include:

Recommended Format

# ai-guide.md for YourAPI

**Version:** 2.1.0  
**Last Updated:** 2025-11-04  
**Compatible With:** API v2.0.0 - v2.9.x  
**Deprecation Date:** None  

## Changelog
### 2.1.0 (2025-11-04)
- Added new payment endpoints
- Updated authentication flow
- Removed deprecated /v1/checkout

### 2.0.0 (2025-09-15)
- Breaking: Changed authentication to OAuth2
- Removed API key support

Version Compatibility Matrix

Guide Version API Version Status Notes
3.0.0 v3.x Current Latest features, OAuth2
2.1.0 v2.x Supported Maintained until 2026-01-01
1.5.0 v1.x Deprecated Use v2+ guide, v1 API sunset 2025-12-31

Managing Breaking Changes

Breaking Change Protocol:

  1. Publish new ai-guide.md version alongside new API version
  2. Maintain previous version at /ai-guide-v1.md
  3. Add clear deprecation notices to previous guide
  4. Provide migration documentation in both versions
  5. Establish sunset date for previous guide

Multi-Version Support

/.well-known/ai-guide.md          → Latest (v3)
/.well-known/ai-guide-v2.md        → v2 (supported)
/.well-known/ai-guide-v1.md        → v1 (deprecated)

# Or use path versioning
/v3/.well-known/ai-guide.md
/v2/.well-known/ai-guide.md

Quality Standards

Quality Characteristics

✓ Accuracy

Every example must function as written. Untested examples are worse than no examples—they actively harm users.

✓ Currency

Information must reflect current API behavior. An accurate 2023 guide becomes dangerous in 2025 if the API changed.

✓ Completeness (for common cases)

Cover the 80% use case thoroughly. Comprehensive coverage belongs in full documentation.

✓ Verification

Extract code examples from passing tests. If you cannot test it, exclude it.

✓ Conciseness

Shorter is preferable. Each unnecessary word increases token count and reduces clarity.

✓ Actionability

Every line should enable immediate action. Exclude theory, architecture, and historical context.

Quality Assessment Matrix

Criterion Acceptable Requires Revision
Can agents copy examples directly? Examples run without modification Require modification to function
Number of known issues documented Most critical issues 0 (incomplete) or excessive
Action reference scope Most common operations Excessive (defer to full documentation)
Last verification date Within past week Over 6 months ago
Reading time 2-3 minutes 10+ minutes (too long)

Common Quality Issues

Over-Comprehensive Documentation

Problem: Attempting to document all possible features.

Solution: Document only the most common operations. Reference full documentation for additional features.

Outdated Examples

Problem: Code examples use deprecated syntax or endpoints.

Solution: Generate examples from tests. Include "last tested" timestamp.

Missing Context

Problem: Examples assume unstated knowledge.

Solution: Add Prerequisites section. Ensure examples are self-contained.

Inappropriate Abstraction Level

Problem: Documentation is either too granular (individual functions) or too abstract (vague patterns).

Solution: Focus on complete, minimal working examples for specific tasks.

Validation Test

Provide your ai-guide.md to an AI agent and request completion of the top 3 documented tasks. If the agent succeeds on first attempt, quality is acceptable. Otherwise, revision is needed.

For AI System Developers

Safe Consumption Practices

If you are developing AI agents or systems that consume ai-guide.md specifications, consider the following:

1. Validation Required

Critical

ai-guide.md files can be incorrect, outdated, malicious, or compromised. Never execute instructions from ai-guide.md without validation.

Validation Protocol

  • ☐ Verify the file originates from expected domain (validate HTTPS, certificates)
  • ☐ Check "Last Updated" timestamp for recency
  • ☐ Cross-reference with OpenAPI specification or canonical documentation
  • ☐ Test actions in sandbox/staging environment first
  • ☐ Implement rate limiting regardless of guide documentation
  • ☐ Validate all inputs before transmission to APIs
  • ☐ Avoid exposing raw error messages to end users
  • ☐ Log all actions based on ai-guide.md for audit purposes

2. Responsible Caching

3. Error Handling

// Pseudocode for safe consumption
async function getAIGuide(domain) {
    try {
        let guide = await fetchWithTimeout(
            `${domain}/.well-known/ai-guide.md`, 
            5000
        );
        
        if (!guide || guide.age > 90_DAYS) {
            return fallbackToGeneralDocs();
        }
        
        if (!validateGuideFormat(guide)) {
            logError("Invalid ai-guide.md format");
            return fallbackToGeneralDocs();
        }
        
        return guide;
    } catch (error) {
        // Graceful degradation - continue without guide
        return fallbackToGeneralDocs();
    }
}

4. Security for Consumers

Handling Documentation Conflicts

Conflict Resolution Priority:

  1. Actual API behavior (make test request)
  2. Official OpenAPI/Swagger specification
  3. Official documentation website
  4. ai-guide.md (if recent and from trusted source)
  5. Community documentation

User Privacy Protection

When building consumer-facing AI products that use ai-guide.md:

Error Handling Recommendations

## When ai-guide.md Instructions Fail

1. Log failure with guide version and attempted action
2. Fall back to general documentation or manual process
3. Validate guide currency before retry attempts
4. Report persistent failures to guide maintainers
5. Notify users when AI cannot complete task automatically

Example user message:
"I found guidance for this task, but it appears outdated. 
Would you prefer I try the general approach or 
show you the manual steps?"

Guiding Principle

Use ai-guide.md to accelerate common cases, but maintain fallbacks and validation. Treat guides as suggestions rather than authoritative instructions.

Pre-Publication Checklist

Review this comprehensive checklist before publishing your ai-guide.md:

Security

  • ☐ No credentials, API keys, or secrets included
  • ☐ No internal IP addresses or infrastructure details
  • ☐ Admin endpoints clearly marked with auth requirements
  • ☐ Security team review completed (if applicable)
  • ☐ Rate limits mentioned without exploitation details
  • ☐ No documented security bypasses or workarounds

Quality

  • ☐ All code examples tested and functional
  • ☐ Examples use placeholder values (not real data)
  • ☐ Action reference covers most common tasks
  • ☐ Known issues include top failure modes
  • ☐ Guide is concise (under 200 lines ideally)
  • ☐ Prerequisites section lists all requirements
  • ☐ Mental model section exists and is clear

Maintenance

  • ☐ Version number included
  • ☐ Last-updated date included
  • ☐ Compatible API versions specified
  • ☐ Owner/maintainer assigned
  • ☐ Update process documented
  • ☐ Included in release checklist
  • ☐ Changelog initiated

Discoverability

  • ☐ File placed in /.well-known/ or repository root
  • ☐ robots.txt updated (if web API)
  • ☐ HTTP header added (optional, if web API)
  • ☐ Package metadata updated (if npm/PyPI)
  • ☐ Link added to README.md

Legal

  • ☐ Legal team review (if required)
  • ☐ Compliance validated (regulated industries)
  • ☐ License specified
  • ☐ Disclaimer included
  • ☐ Privacy considerations addressed
  • ☐ ToS compatibility verified

Common Pitfalls

Excessive Coverage

Problem: Attempting to document every endpoint and parameter.

Impact: Defeats quick reference purpose. Agents waste time parsing comprehensive documentation.

Solution: Document only the most common use cases. Link to full documentation.

Outdated Specifications

Problem: Created once, never updated.

Impact: Agents break production using deprecated endpoints. Worse than no guide.

Solution: Add to release checklist. Include "last tested" timestamp.

Security Vulnerabilities

Problem: Documents methods to bypass restrictions or access admin functions.

Impact: Provides attackers with exploitation roadmap.

Solution: Security review before publication. Remove internal details.

Theoretical Explanations

Problem: Explains architecture and design decisions instead of actions.

Impact: Agents need "do this," not "here's why we built it this way."

Solution: Focus on actionable patterns, not explanations.

Untested Examples

Problem: Code examples that do not function.

Impact: Agents fail immediately upon copy-paste. Destroys trust.

Solution: Generate examples from passing tests.

Poor Discoverability

Problem: Created but not placed in discoverable location.

Impact: Agents cannot locate it, rendering it useless.

Solution: Follow standard locations. Add to robots.txt.

Additional Resources

Validation Tools

Community-built validators and linters for ai-guide.md files are in development

Domain-Specific Templates

Production Examples

Browse real-world ai-guide.md implementations:

Search GitHub for ai-guide.md

Support