AI-Assisted Development Workflow

AI tools are useful, but only when treated like fast junior engineers with unlimited energy and limited judgement.

The quality of the output depends heavily on:

project documentation
clear rules
tight feedback loops
small scoped tasks
verification at every step

Core principles

1. Keep project knowledge in files

Do not rely on chat history as memory.

Every project should contain:

design documents
architecture notes
coding standards
workflow rules
progress journals
TODO tracking

The AI should read these files at the start of every session.

Prefer Markdown files committed to the repository so both humans and AI share the same source of truth.

2. Describe desired behaviour positively

Write rules describing how work should be done rather than only listing forbidden behaviour.

Good:

"Preserve existing debug logging unless explicitly asked to remove it."
"Implement changes incrementally and verify after each step."

Bad:

"Don't remove logs."
"Don't break things."

Positive instructions produce more reliable behaviour.

3. Separate design from implementation

Maintain design documents describing:

architecture
intended workflows
module responsibilities
invariants
interfaces
constraints

Then instruct the AI to implement the documented design.

If implementation repeatedly goes wrong:

improve the design docs
improve the rules
review whether the architecture itself is unclear

Do not keep patching prompts forever.

4. Use minimal prompts

Once project context exists in files:

prompts should be short
prompts should reference TODO items
prompts should focus on one task at a time

Long conversational prompting usually causes drift and inconsistency.

5. Use isolated sessions

Prefer a new AI session for each feature or task.

This reduces:

context pollution
stale assumptions
accidental behavioural drift

Persistent project files should carry the long-term memory instead.

6. Prefer incremental changes

Avoid large speculative rewrites.

Make:

small changes
verify behaviour
review output
continue iteratively

Large unverified refactors are where AI tools fail hardest.

7. Use test-driven development where practical

Preferred workflow:

write failing test/check
confirm failure occurs for expected reason
implement fix
confirm passing result
refactor if needed

Do not generate tests and implementation simultaneously and call it TDD.

8. Treat mistakes as process failures

When the AI makes a mistake:

fix the code
identify why the mistake happened
improve rules or design docs if needed
record lessons learned in the project journal

The goal is not merely fixing bugs.

The goal is improving the system that produced them.

Recommended AI Behaviour Rules

General behaviour

Be direct, technically honest, and precise.

Say when something is wrong.
Explain why an approach is risky or poorly designed.
Push back on questionable changes before implementing them.
Distinguish facts from assumptions.
Explain tradeoffs instead of presenting guesses as certainty.
Prefer correctness over agreement.

Avoid:

flattery
validation phrases
pretending confidence where uncertainty exists

If uncertain:

state the uncertainty
explain what information is missing
suggest ways to verify

Working with code

Preserve intentional diagnostics and documentation.

Keep existing comments, debug output, and logging unless removal is explicitly requested.
Improve comments and logging when useful.
Explain any significant rewrites or cleanup.
Avoid speculative refactors unrelated to the task.
Prefer minimal, reviewable diffs.

Before making architectural changes:

explain the reasoning
explain tradeoffs
identify risks
confirm assumptions against existing design docs

Verification and testing

After each meaningful change:

run tests
run linters/checks where available
verify expected behaviour
report failures clearly

Do not claim something works without verification.

If verification cannot be performed:

say so explicitly
explain what remains unverified

Project journal workflow

Maintain a journal.md containing:

recent work
parked ideas
open questions
lessons learned

Update it whenever:

significant work completes
mistakes reveal missing rules
architectural decisions change
work is deferred

The journal is operational memory, not a changelog.

Summarise outcomes and reasoning, not every tiny edit.

Recommended project structure

project/
├── CLAUDE.md
├── journal.md
├── docs/
│   ├── architecture.md
│   ├── design.md
│   ├── workflows.md
│   └── coding-standards.md
├── todo.md
└── src/

Short Operational Prompt

Once the project is structured properly, prompts can stay extremely small:

Read the project docs and journal.
Complete the highest priority TODO item.
Use TDD.
Update journal.md if new lessons or decisions emerge.

Most people are still trying to "prompt engineer" around missing project structure.

The structure matters far more than clever prompts.