Skip to content

Commit b2269aa

Browse files
committed
docs: Remove temporary AI-generated files and add documentation guidelines
Remove temporary work artifacts that don't provide lasting value: - MIGRATION_SUMMARY.md (migration process notes) - PR_REVIEW_RESPONSE_PLAN.md (review response planning) - REVIEW_RESPONSE.md (review response notes) These files were AI-generated intermediate work products that belong in PR descriptions/comments or git commit messages, not in the repository. Add new section to CLAUDE.md: "When to Create Documentation Files" Provides clear guidance on: - What should be top-level .md files (user docs, standards) - What should NOT be top-level files (temporary artifacts, PR context) - Where to put that content instead (commits, PRs, issues, docs/) Addresses review feedback about avoiding generic AI-generated markdown files that clutter the repository without providing user value.
1 parent 5f75b1b commit b2269aa

File tree

4 files changed

+34
-680
lines changed

4 files changed

+34
-680
lines changed

CLAUDE.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -893,6 +893,40 @@ Special lab track for leadership training located in `docs/labs/director-trainin
893893
- Structured exercises for understanding the vTeam system from a strategic perspective
894894
- Validation reports for tracking completion and understanding
895895

896+
### When to Create Documentation Files
897+
898+
**DO create top-level `.md` files when:**
899+
900+
- **User-facing documentation**: `README.md`, `QUICK_START.md`, `CONTRIBUTING.md`
901+
- **Coding standards**: `CLAUDE.md`, `BRANCH_PROTECTION.md`
902+
- **Important architectural decisions**: ADRs that users/contributors need to reference
903+
- **The file provides lasting value** to anyone using or contributing to the repo
904+
905+
**DO NOT create top-level `.md` files for:**
906+
907+
- **Temporary work artifacts**: Migration summaries, review response plans, analysis notes
908+
- **PR-specific context**: This belongs in PR description or comments, not repo files
909+
- **AI brainstorming output**: Planning documents, strategy explorations, intermediate analysis
910+
- **Process documentation**: How a specific PR was reviewed/developed
911+
912+
**Instead, put that content:**
913+
914+
- **Git commit messages**: Detailed explanation of what/why you changed
915+
- **PR descriptions**: Context about the feature, trade-offs, testing approach
916+
- **PR comments**: Responses to reviews, clarifications, discussion
917+
- **Issue descriptions**: Track future work, document known limitations
918+
- **Docs folder**: `docs/` for substantial guides that aren't top-level worthy
919+
920+
**The test:** Would a new developer or user in 6 months need this file? If not, it's temporary context that belongs in git history or GitHub discussions, not the repository root.
921+
922+
**Examples of good top-level docs in this repo:**
923+
924+
- `README.md` - Project overview, installation, usage
925+
- `QUICK_START.md` - Get running in 5 minutes
926+
- `CONTRIBUTING.md` - How to contribute code
927+
- `CLAUDE.md` - Coding standards and patterns
928+
- `BRANCH_PROTECTION.md` - Git workflow and protection rules
929+
896930
## Production Considerations
897931

898932
### Security

MIGRATION_SUMMARY.md

Lines changed: 0 additions & 240 deletions
This file was deleted.

0 commit comments

Comments
 (0)