Phil Skentelbery
354c18b5b8
Added "Documentation Navigation" section with: - Clear explanation of docs/ folder structure and purpose of each subdirectory - Guidelines for finding existing documentation before implementing features - Practical rules for when to create ADRs, design docs, reports, or standards - File naming conventions for different document types This improves agent and developer ability to navigate the documentation system and maintain proper organization standards. Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
92 lines
3.7 KiB
Markdown
92 lines
3.7 KiB
Markdown
# Claude Agent Instructions
|
|
|
|
This file contains operational instructions for Claude agents working on this project.
|
|
|
|
## Python Environment
|
|
|
|
- We use **uv** for Python virtual environment management
|
|
- All Python commands must be run with `uv run` prefix
|
|
- Example: `uv run pytest`, `uv run flask run`
|
|
|
|
## Agent-Developer Protocol
|
|
|
|
When invoking the agent-developer, always remind it to:
|
|
|
|
1. **Document work in reports**
|
|
- Create implementation reports in `docs/reports/`
|
|
- Include date in filename: `YYYY-MM-DD-description.md`
|
|
|
|
2. **Update the changelog**
|
|
- Add entries to `CHANGELOG.md` for user-facing changes
|
|
- Follow existing format
|
|
|
|
3. **Version number management**
|
|
- Increment version numbers according to `docs/standards/versioning-strategy.md`
|
|
- Update version in `starpunk/__init__.py`
|
|
|
|
4. **Follow git protocol**
|
|
- Adhere to git branching strategy in `docs/standards/git-branching-strategy.md`
|
|
- Create feature branches for non-trivial changes
|
|
- Write clear commit messages
|
|
|
|
## Documentation Navigation
|
|
|
|
### Understanding the docs/ Structure
|
|
|
|
The `docs/` folder is organized by document type and purpose:
|
|
|
|
- **`docs/architecture/`** - System design overviews, component diagrams, architectural patterns
|
|
- **`docs/decisions/`** - Architecture Decision Records (ADRs), numbered sequentially (ADR-001, ADR-002, etc.)
|
|
- **`docs/deployment/`** - Deployment guides, infrastructure setup, operations documentation
|
|
- **`docs/design/`** - Detailed design documents, feature specifications, phase plans
|
|
- **`docs/examples/`** - Example implementations, code samples, usage patterns
|
|
- **`docs/projectplan/`** - Project roadmaps, implementation plans, feature scope definitions
|
|
- **`docs/reports/`** - Implementation reports from developers (dated: YYYY-MM-DD-description.md)
|
|
- **`docs/reviews/`** - Architectural reviews, design critiques, retrospectives
|
|
- **`docs/standards/`** - Coding standards, conventions, processes, workflows
|
|
|
|
### Where to Find Documentation
|
|
|
|
- **Before implementing a feature**: Check `docs/decisions/` for relevant ADRs and `docs/design/` for specifications
|
|
- **Understanding system architecture**: Start with `docs/architecture/overview.md`
|
|
- **Coding guidelines**: See `docs/standards/` for language-specific standards and best practices
|
|
- **Past implementation context**: Review `docs/reports/` for similar work (sorted by date)
|
|
- **Project roadmap and scope**: Refer to `docs/projectplan/`
|
|
|
|
### Where to Create New Documentation
|
|
|
|
**Create an ADR (`docs/decisions/`)** when:
|
|
- Making architectural decisions that affect system design
|
|
- Choosing between competing technical approaches
|
|
- Establishing patterns that others should follow
|
|
- Format: `ADR-NNN-brief-title.md` (find next number sequentially)
|
|
|
|
**Create a design doc (`docs/design/`)** when:
|
|
- Planning a complex feature implementation
|
|
- Detailing technical specifications
|
|
- Documenting multi-phase development plans
|
|
|
|
**Create an implementation report (`docs/reports/`)** when:
|
|
- Completing significant development work
|
|
- Documenting implementation details for architect review
|
|
- Format: `YYYY-MM-DD-brief-description.md`
|
|
|
|
**Update standards (`docs/standards/`)** when:
|
|
- Establishing new coding conventions
|
|
- Documenting processes or workflows
|
|
- Creating checklists or guidelines
|
|
|
|
### Key Documentation References
|
|
|
|
- **Architecture**: See `docs/architecture/overview.md`
|
|
- **Implementation Plan**: See `docs/projectplan/v1/implementation-plan.md`
|
|
- **Feature Scope**: See `docs/projectplan/v1/feature-scope.md`
|
|
- **Coding Standards**: See `docs/standards/python-coding-standards.md`
|
|
- **Testing**: See `docs/standards/testing-checklist.md`
|
|
|
|
## Project Philosophy
|
|
|
|
"Every line of code must justify its existence. When in doubt, leave it out."
|
|
|
|
Keep implementations minimal, standards-compliant, and maintainable.
|