Skip to content

— icon: lucide/compass

General Guidelines

Best practices that apply across all dotStandards. These are recommendations, not rules — adapt them to your workflow.

Standard-specific extensions

Use these pages for concrete rules per standard. They extend this page and apply in addition to it.

Getting started

Start with the minimum required structure and grow organically. Each standard defines what a minimal valid directory looks like — begin there. Don’t scaffold empty directories for layers you aren’t using yet.

Content quality

Write for both humans and LLMs. Files in dotStandards directories are read by people and consumed by AI agents, so clarity matters more than completeness.

  • Keep files self-contained. Each file should make sense on its own without requiring the reader to chase references.
  • Prefer structured content. Use headings, lists, and definition lists over long prose paragraphs. Structured content is easier to scan and easier for tools to parse.
  • Be specific. Concrete details are more useful than generic statements. “Use Go 1.22 with modules” beats “Use a modern language.”
  • Omit the obvious. Don’t document things that are already implied by the file’s location or name.

Maintenance

dotStandards directories are only useful if they reflect reality.

  • Keep files up to date. When your stack, role, or project setup changes, update the relevant files.
  • Remove stale information. Outdated content is worse than no content — it actively misleads tools and agents.
  • Review periodically. Set a cadence (monthly, quarterly) to scan your dotStandards directories and prune anything that no longer applies.

Security and privacy

dotStandards directories contain information that tools and agents read automatically. Be deliberate about what you put in them.

  • Never store secrets. No API keys, tokens, passwords, or credentials. Use your system’s credential store or environment variables.
  • Version control carefully. If your dotStandards directory is checked into a repository or synced to a service, review its contents for anything sensitive before sharing.

Portability

  • Stick to plain Markdown and YAML. Avoid tool-specific extensions, custom syntax, or proprietary formats.
  • Use relative paths within dotStandards directories where possible.
  • Don’t depend on a specific OS. File names, paths, and content should work across platforms.

Coexistence

dotStandards are independent. Each standard covers a different scope (user-level vs. project-level) and a different purpose. You can adopt them individually or together.

  • Don’t duplicate information between standards. User-level preferences belong in .agents, project-level configuration belongs in .forge.
  • Don’t cross-reference between standards unless there’s a clear reason. Each directory should be self-sufficient.