Acyclic.eu elevating people and products

2

Design_principles

09 Jun 2025

Following is my design system principles as part of my AI coding Prompt. Feel free to add suggestions of improvement.

Design Principles

This project follows established software design paradigms to ensure maintainability and clarity. All contributors (AI and human) should adhere to these principles. For full definitions, see the linked resources. Only project-specific clarifications are listed here.

1. Hexagonal Architecture (Ports and Adapters)

1.1 Hexagonal Architecture (Wikipedia)

2. SOLID Principles

2.1 SOLID (Wikipedia)

3. Law of Demeter

3.1 Law of Demeter (Wikipedia) 3.2 When using language or library constructs, it is acceptable to “call strangers” within those constructs. You do not need to mirror the dependency structure in your own code.

4. Naming and Style

4.1 Kotlin Coding Conventions.

5. Refactoring

5.1 Refactoring

6. YAGNI (You Aren’t Gonna Need It)

6.1 YAGNI (Wikipedia)

7. DRY (Don’t Repeat Yourself)

7.1 DRY (Wikipedia)

8. Defensive Programming

8.1 Defensive Programming (Wikipedia)

9. Test-Driven Development (TDD)

9.1 TDD (Wikipedia) 9.2 production code should be motivate by tests.

10. Continuous Delivery

10.1 Continuous Delivery

12. KISS (Keep It Simple, Stupid)

12.1 KISS Principle (Wikipedia)

13. Principle of Least Astonishment

13.1 Principle of Least Astonishment (Wikipedia)

14. Separation of Concerns

14.1 Separation of Concerns (Wikipedia)

17. Minimum Viable Product (MVP)

17.1 Minimum Viable Product (Wikipedia)

16. Best Simple System for Now

16.1 Best Simple System for Now (Dan North)

15. Composition Over Inheritance

15.1 Composition Over Inheritance (Wikipedia)

For inspiration and guidance, consider the work and teachings of: Martin Fowler, Kent Beck, Alistair Cockburn, Emily Bache, Samuel Ytterbrink, Allen Holub, Michael Feathers, Dan North, David Farley, and Mary Poppendieck.

Ai Coding Prompt

09 Jun 2025

How I Structure AI Instructions for My Codebase

As AI tools like GitHub Copilot and automated code review agents become more integrated into my development workflow, the way I instruct these tools is just as important as how I instruct human collaborators. After several iterations, I’ve settled on a structure that keeps my project’s AI guidance clear, maintainable, and always in sync with my core goals and principles.

The Core Idea: Centralize, Don’t Repeat

Instead of scattering AI instructions across multiple configuration files or repeating design principles in every tool, I use a single source of truth: AI_PROMPT.md at the root of my repository.

Why Centralize?

  • Consistency: All AI tools reference the same prompt, so there’s no risk of conflicting or outdated instructions.
  • Maintainability: When my design principles or product goals change, I only need to update one place.
  • Onboarding: New contributors (human or AI) can quickly find out how to “think” about my codebase.

The Structure

1. AI_PROMPT.md

This file contains a simple instruction:

For all AI-assisted code generation, refactoring, and documentation in this project, follow the guidance and requirements in:

Do not repeat or summarize their content here—always refer to those documents directly for the latest rules and clarifications.

When generating AI configuration or AI meta files, always include a reference to this AI_PROMPT.md for future maintainers.

2. Reference in All AI Configurations

Both my Copilot and Juni agent configuration files contain only a single line referencing the central prompt. Here’s where you’ll find them in my repo:

  • Copilot config: .github/copilot.yml
  • Juni agent config: .juni/agent-guidelines.yml

Each file contains:

instructions: |
  Refer to the AI prompt in AI_PROMPT.md at the root of this repository for all guidance.

This keeps the configs clean and ensures every tool is aligned.

3. Design Principles and Product Goal

  • DESIGN_PRINCIPLES.md contains all my architectural and coding standards (Hexagonal, SOLID, YAGNI, etc.).
  • PRODUCT_GOAL.md describes the MVP and vision for my project.

Benefits I’ve Noticed

  • Less Drift: No more out-of-sync instructions between tools.
  • Easier Refactoring: I can update my principles or goals without hunting through config files.
  • Better AI Output: The AI is more likely to generate code that fits my standards and product vision.
  • Potential for Clearer Collaboration: If I would work with others, contributors will know exactly where to look for my project philosophy.

Insights and Open Questions

  • How do you keep your AI instructions in sync?
  • Have you found ways to make AI-generated code even more aligned with your style?
  • What pitfalls have you encountered with AI configuration drift?

I’d love to hear how other developers are structuring their AI guidance. If you have tips, feedback, or want to share your own approach, let’s connect!

Feel free to adapt this structure for your own projects, and let me know if it helps!