AI Coding Principles
Best practice structures and workflows to maximize time in flow.
Flow is the ultimate goal.
State of Play
Software development is now about guiding the intentions of intelligent systems through prompts.
- Prompt-Centric Development: Prompts are now central to programming, enabling multi-step workflows and dynamic problem-solving.
- High-Grade Compute: Investing in advanced AI models yields significant productivity improvements compared to cost-saving approaches using lower-grade models.
- Resistance to Change: Those unwilling to adapt will fall far behind engineers that embrace generative AI's capabilities.
Principles
Prompt-Centric Development
Balance prompt detail, with just enough context and the right LLM for the task at hand.
- Keep things simple, particularly when starting out
- Choose the right tools to constrain agent behavior
- Aim to only use prompts over writing code
- Plan out specs with prompts
- Factor out a library of reusable prompts
Manage Context
Manage context to achieve results. Clarity of intentions is even more important with AI tools to communicate context, processes and desired outcomes to ensure solutions have a clean architecture and avoid wasting compute time and tokens.
- Product Requirements Document
- Diagraming Toolkit
- Clean Architecture
- Component Driven Design
- Software Algorithms
Compute Power
Choose the right model for the complexity of the task.
Planning
- Plan before you code: Clarify vision, architecture, and constraints in writing.
- Track tasks separately: Keep actionable work distinct from high-level planning.
- Document everything: Modular, persistent documentation helps maintain context and continuity.
- Enforce standards: Use configuration files to guide both human and automated contributors.
- Iterate and update: Continuously refine your plans and tasks as the project evolves.
File and Purposes:
| File/Directory | Purpose | Importance |
|---|---|---|
| PLANNING.md | High-level vision & architecture | Guides all decisions, prevents drift |
| TASK.md | Track tasks, backlog, and milestones | Maintains focus and progress |
| .projectrules | Project-specific standards & rules | Ensures consistency and compliance |
| docs/plans/ | Modular planning documents | Supports detailed, persistent context |
| logs/tasks/ | Task history and rationale | Enables continuity and learning |
| README.md | Overview and instructions | Essential for onboarding and clarity |
PLANNING.md
- Purpose: High-level vision, architecture, constraints, tech stack, tools, etc.
- Prompt to AI: “Use the structure and decisions outlined in PLANNING.md.”
- Have the LLM reference this file at the beginning of any new conversation.
TASK.md
- Purpose: Tracks current tasks, backlog, and sub-tasks.
- Includes: Bullet list of active work, milestones, and anything discovered mid-process.
- Prompt to AI: “Update TASK.md to mark XYZ as done and add ABC as a new task.”
- Can prompt the LLM to automatically update and create tasks as well (through global rules).
Workflow
- Initialization: Start each session by loading PLANNING.md and .windsurfrules into the AI's context. Review the latest .windsurf/task-logs/ to understand current state.
- Planning Phase: Update or refine PLANNING.md and .windsurf/plans/* as requirements evolve. Document all new insights before coding.
- Task Management: Use TASK.md to break down work into actionable items. As tasks are completed, update TASK.md and log changes in .windsurf/task-logs/.
- Implementation: Follow the prioritized plan (feature-order.md), referencing UI/UX, db-schema, and complexity-analysis as needed. Enforce standards via .windsurfrules.
- Documentation: After each session, update all relevant files—especially task logs and planning artifacts—to leave clear "reminder notes" for the next session.
- Review and Refactor: Use refactor.md (if present) to guide large changes, checking off steps as you go.