Using AIDD-17 with AI

Why this matters

AIDD-17 gives AI a project definition to work from. The goal is to stop AI guessing product intent, architecture, scope, process, or verification rules. AI should use AIDD-17 as context before implementation begins.

Basic workflow

1. Define or update the AIDD-17 project definition.
2. Create an implementation slice.
3. Give the implementation slice to AI.
4. Ask AI to work only within the slice.
5. Review the output against the verification rules.
6. Update the project definition if the implementation changes the design.

What AI should read

Before implementation, AI should be given:

• relevant AIDD-17 sections
• the implementation slice
• related decision records
• relevant interfaces or data definitions
• applicable verification rules

For small projects, the whole AIDD-17 document may be used. For larger projects, provide the relevant sections and links.

Standard AI instruction

Use this instruction when giving a slice to an AI coding agent:

ai-instruction.txt

Read the AIDD-17 project definition and the assigned implementation slice.

Implement only the assigned slice.

Do not implement out-of-scope items.

Do not invent product behaviour, architecture, interfaces, delivery rules, or verification criteria.

Do not modify files outside the expected scope unless you explain why the change is required.

Stop and report if required information is missing, contradictory, or ambiguous.

Return:
- summary of changes
- files changed
- tests added or changed
- assumptions made
- unresolved questions
- verification performed

When AI must stop

AI must stop when:

• required product behaviour is undefined
• architecture is missing or contradictory
• an interface is not defined
• a data structure is unclear
• a rule conflicts with another rule
• the slice requires changing out-of-scope areas
• verification criteria are missing
• security, privacy, or compliance impact is unclear

Stopping is not failure

Stopping prevents drift. An AI that asks before acting is doing the right thing.

What AI may do — and what it may not own

AI may assist with:

• implementation planning
• code changes
• tests
• documentation updates
• review checklists
• refactoring within scope
• identifying gaps
• proposing follow-up slices

AI may not own:

• product direction
• architecture decisions
• delivery process
• acceptance of work
• security approval
• release approval

Good and bad AI tasks

Good task

Implement IMP-001 Create Text Document.

Use the linked AIDD-17 sections:
- B-001 Create text document
- F-001 Text document capture
- POST /documents
- Document record
- Upload verification

Stay within the scope of IMP-001.

Do not implement text processing, embeddings, indexing, or question answering.

Return files changed, tests added, assumptions, and verification performed.

Bounded scope, linked context, explicit out-of-scope items, defined return format.

Bad task

Build the document assistant.

Too broad. Gives AI room to invent scope, architecture, and behaviour.

Review AI output

Review the output against:

• linked behaviours
• linked features
• architecture sections
• applicable rules
• scope
• out of scope
• verification criteria

Caution

The question is not “did AI write code?” — it is “did the work satisfy the project definition?”