Project: Collect Files
Version: 1.0
Status: Official
This handbook is the primary entry point for developers.
It explains:
- where to start
- how the project is organized
- how to implement new features
- how to fix bugs
- how to review changes
- which documents to consult
Every contributor should read this handbook before modifying the project.
Recommended reading sequence
00_PROJECT_VISION.md
↓
01_REQUIREMENTS.md
↓
02_ARCHITECTURE.md
↓
03_PROJECT_STRUCTURE.md
↓
04_DOMAIN_MODELS.md
↓
05_PIPELINE.md
↓
06_COMPONENTS.md
↓
07_CONFIGURATION.md
↓
08_CODING_STANDARDS.md
↓
09_ERROR_HANDLING.md
↓
10_LOGGING.md
↓
11_TESTING.md
↓
12_CLI_SPECIFICATION.md
↓
13_ROADMAP.md
↓
14_CONTRIBUTING.md
↓
15_API_REFERENCE.md
↓
16_GLOSSARY.md
↓
17_DECISIONS.md
↓
18_CHANGELOG.md
Following this order provides the necessary context before implementation begins.
The recommended workflow is:
Read documentation
↓
Understand architecture
↓
Identify affected modules
↓
Design solution
↓
Implement
↓
Write tests
↓
Update documentation
↓
Run validation
↓
Submit changes
Documentation should be updated as part of the implementation rather than afterward.
When adding a feature:
- Verify that it aligns with the project vision.
- Check whether an ADR is required.
- Identify the pipeline stage involved.
- Determine affected domain models.
- Minimize architectural impact.
- Implement the feature.
- Add unit tests.
- Add integration tests if required.
- Update documentation.
- Verify deterministic behavior.
Recommended process
Reproduce
↓
Identify root cause
↓
Write failing test
↓
Implement fix
↓
Verify regression
↓
Update changelog
Avoid speculative fixes.
Fix the underlying cause rather than symptoms.
Refactoring should:
- preserve observable behavior
- improve readability
- simplify maintenance
- reduce complexity
Refactoring must not introduce new features.
Documentation is part of the codebase.
Whenever behavior changes:
Update the corresponding document before merging.
Documentation should never lag behind implementation.
Before changing any module, ask:
- Does this violate SRP?
- Does this introduce coupling?
- Does this create circular imports?
- Does this move responsibilities across layers?
- Does this preserve determinism?
If any answer is "yes", reconsider the design.
Before merging:
Run formatter.
Run linter.
Run type checker.
Run unit tests.
Run integration tests.
Review logs.
Review documentation.
AI tools are encouraged for:
- boilerplate
- documentation
- refactoring suggestions
- test generation
- API design discussions
Human review remains mandatory.
Never merge AI-generated code without verification.
Provide:
- the relevant architecture document
- the affected module
- the coding standards
- the expected behavior
Avoid asking for large unrelated changes in a single prompt.
Prefer incremental modifications.
Before each release:
✓ Tests pass
✓ Documentation updated
✓ Changelog updated
✓ Version updated
✓ Roadmap reviewed
✓ Public API reviewed
✓ CLI verified
✓ Logging verified
✓ Error handling verified
✓ No architectural regressions
The project should evolve through:
small,
well-tested,
well-documented,
incremental improvements.
Large rewrites should be avoided unless justified by an ADR.
collect-files/
├── cache/
├── docs/
│ ├── 00_PROJECT_VISION.md
│ ├── 01_REQUIREMENTS.md
│ ├── 02_ARCHITECTURE.md
│ ├── 03_PROJECT_STRUCTURE.md
│ ├── 04_DOMAIN_MODELS.md
│ ├── 05_PIPELINE.md
│ ├── 06_COMPONENTS.md
│ ├── 07_CONFIGURATION.md
│ ├── 08_CODING_STANDARDS.md
│ ├── 09_ERROR_HANDLING.md
│ ├── 10_LOGGING.md
│ ├── 11_TESTING.md
│ ├── 12_CLI_SPECIFICATION.md
│ ├── 13_ROADMAP.md
│ ├── 14_CONTRIBUTING.md
│ ├── 15_API_REFERENCE.md
│ ├── 16_GLOSSARY.md
│ ├── 17_DECISIONS.md
│ ├── 18_CHANGELOG.md
│ └── 19_DEVELOPER_HANDBOOK.md
│
├── logs/
├── tests/
├── core/
├── collect_files.py
├── pyproject.toml
├── requirements.txt
└── README.md
Every improvement should make the project:
- simpler
- safer
- more deterministic
- easier to understand
- easier to test
- easier to maintain
Correctness always takes precedence over cleverness.
The architecture is a long-term asset and should be protected accordingly.