LLM Harness
191 lines
3.9 KiB
Plaintext
191 lines
3.9 KiB
Plaintext
# MODULE STRUCTURE TEMPLATE
|
|
|
|
**Standard structure for any module within a project harness.**
|
|
|
|
---
|
|
|
|
## Module Anatomy
|
|
|
|
```
|
|
modules/[module-name]/
|
|
├── APPROACH.md ← How to execute this phase
|
|
├── CHECKLIST.md ← What to verify
|
|
├── SPEC.md ← What to build (input for agent)
|
|
└── [outputs]/ ← Generated by agent
|
|
├── DESIGN.md
|
|
├── SCHEMA.md
|
|
└── ...
|
|
```
|
|
|
|
---
|
|
|
|
## APPROACH.md
|
|
|
|
**Purpose:** Tell agents HOW to execute this phase.
|
|
|
|
```markdown
|
|
# [Phase Name] Approach
|
|
|
|
## Goal
|
|
[What should be accomplished]
|
|
|
|
## Process
|
|
1. [Step 1]
|
|
2. [Step 2]
|
|
3. [Step 3]
|
|
|
|
## Constraints to Respect
|
|
- [Constraint 1]
|
|
- [Constraint 2]
|
|
|
|
## Success Criteria
|
|
- [Criterion 1]
|
|
- [Criterion 2]
|
|
|
|
## Output Files
|
|
- [file1.md]
|
|
- [file2.md]
|
|
```
|
|
|
|
---
|
|
|
|
## CHECKLIST.md
|
|
|
|
**Purpose:** Verify the phase completed correctly.
|
|
|
|
```markdown
|
|
# [Phase Name] Checklist
|
|
|
|
## Functional
|
|
- [ ] All requirements from SPEC.md are met
|
|
- [ ] All constraints are satisfied
|
|
- [ ] No blocking open questions
|
|
|
|
## Quality
|
|
- [ ] Follows code/design standards
|
|
- [ ] Performance targets met
|
|
- [ ] Security considerations addressed
|
|
|
|
## Documentation
|
|
- [ ] All decisions documented
|
|
- [ ] Rationales explained
|
|
- [ ] Ambiguities clarified
|
|
|
|
## Ready for Next Phase?
|
|
- [ ] All checkboxes above passed
|
|
- [ ] No blockers remain
|
|
```
|
|
|
|
---
|
|
|
|
## SPEC.md (Example)
|
|
|
|
**Purpose:** Define requirements for the agent.
|
|
|
|
```markdown
|
|
# [Module] Specification
|
|
|
|
## Overview
|
|
[What problem does this solve?]
|
|
|
|
## Requirements
|
|
1. [Functional requirement 1]
|
|
2. [Functional requirement 2]
|
|
3. [Non-functional requirement]
|
|
|
|
## Constraints (from project CONSTRAINTS.md)
|
|
- [Constraint 1]
|
|
- [Constraint 2]
|
|
|
|
## Acceptance Criteria
|
|
- [Criterion 1]
|
|
- [Criterion 2]
|
|
|
|
## Related Files
|
|
- Architecture: [link]
|
|
- Database: [link]
|
|
- Testing: [link]
|
|
```
|
|
|
|
---
|
|
|
|
## Module Loading Example
|
|
|
|
When bribing Claude Code for "design" phase:
|
|
|
|
```bash
|
|
# Load these files (and ONLY these):
|
|
- ~/workspace/[project]/HARNESS.md (project structure)
|
|
- ~/workspace/[project]/modules/design/APPROACH.md (how to execute)
|
|
- ~/workspace/[project]/modules/design/SPEC.md (what to build)
|
|
- ~/workspace/[project]/modules/design/CHECKLIST.md (success criteria)
|
|
- ~/workspace/gravl/modules/design/CONSTRAINTS.md (from parent)
|
|
|
|
# Output expected:
|
|
- ~/workspace/[project]/modules/design/ARCHITECTURE.md
|
|
- ~/workspace/[project]/modules/design/ER-DIAGRAM.md
|
|
- ~/workspace/[project]/modules/design/DECISION_LOG.md
|
|
```
|
|
|
|
---
|
|
|
|
## Minimal Data Principle
|
|
|
|
✅ **DO load:**
|
|
- Module specs for THIS phase
|
|
- Related specs from same project
|
|
- Constraints that affect THIS phase
|
|
|
|
❌ **DON'T load:**
|
|
- Future phase modules
|
|
- Implementation code
|
|
- Test files
|
|
- Other projects
|
|
- Unused historical context
|
|
|
|
**Goal:** Agent has EXACTLY what it needs, nothing more.
|
|
|
|
---
|
|
|
|
## Example: Design Module
|
|
|
|
```
|
|
modules/design/
|
|
├── APPROACH.md ← "Design system architecture"
|
|
├── CHECKLIST.md ← "All constraints verified?"
|
|
├── SPEC.md ← "Build database schema + API spec"
|
|
├── CONSTRAINTS.md ← "Performance, security, scaling"
|
|
├── EXISTING_ARCHITECTURE.md ← "Current system overview"
|
|
└── [outputs]/
|
|
├── SCHEMA.md ← Agent creates this
|
|
├── API_SPEC.md ← Agent creates this
|
|
├── DECISIONS.md ← Agent creates this
|
|
└── ER_DIAGRAM.md ← Agent creates this
|
|
```
|
|
|
|
When bribing agent for design:
|
|
```
|
|
Load:
|
|
- APPROACH.md
|
|
- SPEC.md
|
|
- CONSTRAINTS.md
|
|
- EXISTING_ARCHITECTURE.md
|
|
|
|
Don't load:
|
|
- implementation/
|
|
- testing/
|
|
- docs/
|
|
```
|
|
|
|
---
|
|
|
|
## Best Practices
|
|
|
|
1. **Keep specs focused** — One module = one task
|
|
2. **Document decisions** — Why, not just what
|
|
3. **Version constraints** — Tag major constraint changes
|
|
4. **Link related modules** — Show dependencies
|
|
5. **Checkpoint at boundaries** — Save state between phases
|
|
|
|
This keeps context minimal and agents focused.
|