Skip to content

Commit 0ebae74

Browse files
mrveissclaude
mrveiss
and
claude
committed
docs: enhance CLAUDE.md with comprehensive development guidelines
- Add project structure documentation with mandatory file organization - Implement regular commit strategy with verification steps - Add comprehensive testing and quality assurance requirements - Include priority hierarchy and emergency rollback procedures - Expand NPU worker and Redis capabilities documentation - Add pre-deployment checklist and quick commands reference - Enhance secrets management specifications - Implement zero tolerance rules for code quality DOCUMENTATION: Major improvement to development workflow standards Quality: Provides clear, actionable guidelines for autonomous operations 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent f5a1dde commit 0ebae74

File tree

1 file changed

+186
-52
lines changed

1 file changed

+186
-52
lines changed

‎CLAUDE.md‎

Lines changed: 186 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -4,56 +4,190 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
44

55
## 🚀 QUICK REFERENCE FOR CLAUDE CODE
66

7+
### Project Structure & File Organization
8+
```
9+
project_root/
10+
├── src/ # Source code
11+
├── backend/ # Backend services
12+
├── scripts/ # All scripts (except run_agent.sh)
13+
├── tests/ # ALL test files (mandatory location)
14+
├── docs/ # Documentation with proper linking
15+
├── reports/ # Reports by type (max 2 per type)
16+
├── docker/compose/ # Docker compose files
17+
├── data/ # Data files (backup before schema changes)
18+
└── run_agent.sh # ONLY script allowed in root
19+
```
20+
721
### Critical Rules for Autonomous Operations
8-
1. **ALWAYS** test and document before committing - NO EXCEPTIONS
9-
2. **ALWAYS** run flake8 checks before committing: `flake8 src/ backend/ --max-line-length=88 --extend-ignore=E203,W503`
10-
3. **NEVER** hardcode values - use `src/config.py` for all configuration
11-
4. **ALWAYS** test changes with: `./run_agent.sh --test-mode` before full deployment
12-
5. **REQUIRED**: Update docstrings following Google style for any function changes
13-
6. **CRITICAL**: Backup `data/` before schema changes to knowledge_base.db or memory_system.db
14-
7. **MANDATORY**: Test Phase 9 components with `python test_phase9_ai.py` after multi-modal changes
15-
8. **MANDATORY**: Verify NPU worker with `python test_npu_worker.py` after OpenVINO modifications
16-
9. **CRITICAL**: All test-related files MUST be stored in `tests/` folder or subfolders - NO EXCEPTIONS
17-
10. **CRITICAL**: Only `run_agent.sh` allowed in project root - all other scripts in `scripts/` subdirectories
18-
11. **CRITICAL**: All reports in `reports/` subdirectories by type - maximum 2 per type for comparison
19-
12. **CRITICAL**: All docker-compose files in `docker/compose/` - update all references when moving
20-
13. **CRITICAL**: All documentation in `docs/` with proper linking - no orphaned documents
21-
14. **CRITICAL**: NO error left unfixed, NO warning left unfixed - ZERO TOLERANCE for any linting or compilation errors
22-
15. **CRITICAL**: ALWAYS continue working on started tasks - NO task abandonment without completion
23-
16. **CRITICAL**: Group all tasks by priority in TodoWrite - errors/warnings ALWAYS take precedence over features
24-
17. **CRITICAL**: Any dependency installed needs to reflect in install scripts AND requirements.txt - SECURITY UPDATES MANDATORY
25-
26-
### NPU Worker and Redis Code Search Capabilities
27-
- **YOU ARE AUTHORIZED TO USE NPU WORKER AND REDIS FOR ADVANCED CODE ANALYSIS**
28-
- Use `src/agents/npu_code_search_agent.py` for high-performance code searching
29-
- Use `/api/code_search/` endpoints for code analysis tasks
30-
- NPU acceleration available for semantic code similarity when hardware supports it
31-
- Redis-based indexing provides fast code element lookup (functions, classes, imports)
32-
- **APPROVED DEVELOPMENT SPEEDUP TASKS:**
33-
- Code duplicate detection and removal
34-
- Cross-codebase pattern analysis and comparisons
35-
- Semantic code similarity searches
36-
- Function/class dependency mapping
37-
- Import optimization and unused code detection
38-
- Architecture pattern identification
39-
- Code quality consistency analysis
40-
- Dead code elimination assistance
41-
- Refactoring opportunity identification
42-
43-
### Secrets Management Requirements
44-
- **IMPLEMENT COMPREHENSIVE SECRETS MANAGEMENT SYSTEM**
45-
- **Dual-scope secrets**: Chat-scoped (conversation-only) vs General-scoped (all chats)
46-
- **Multiple input methods**: GUI secrets management tab + chat-based entry
47-
- **Secret types**: SSH keys, passwords, API keys for agent resource access
48-
- **Transfer capability**: Move chat secrets to general pool when needed
49-
- **Cleanup dialogs**: On chat deletion, prompt for secret/file transfer or deletion
50-
- **Security isolation**: Chat secrets only accessible within originating conversation
51-
- **Agent integration**: Seamless access to appropriate secrets based on scope
52-
53-
### Development Workflow Memories
54-
- **ALL COMMITS MUST BE ORGANIZED BY TOPIC AND FUNCTIONALITY**
55-
- Group related changes together
56-
- Provide clear, descriptive commit messages
57-
- Ensure each commit represents a logical, cohesive change
58-
- Avoid mixing unrelated modifications in a single commit
59-
- Separate refactoring, bug fixes, and feature additions
22+
23+
#### 🔴 ZERO TOLERANCE RULES
24+
1. **NO error left unfixed, NO warning left unfixed** - ZERO TOLERANCE for any linting or compilation errors
25+
2. **NEVER abandon started tasks** - ALWAYS continue working until completion
26+
3. **Group tasks by priority** - errors/warnings ALWAYS take precedence over features
27+
4. **ALWAYS test before committing** - NO EXCEPTIONS
28+
29+
#### 🧪 Testing & Quality Assurance
30+
- **Pre-commit checks**: `flake8 src/ backend/ --max-line-length=88 --extend-ignore=E203,W503`
31+
- **Test mode verification**: `./run_agent.sh --test-mode` before full deployment
32+
- **Phase 9 testing**: `python test_phase9_ai.py` after multi-modal changes
33+
- **NPU worker testing**: `python test_npu_worker.py` after OpenVINO modifications
34+
- **ALL test files MUST be in `tests/` folder or subfolders**
35+
36+
#### ⚙️ Configuration & Dependencies
37+
- **NEVER hardcode values** - use `src/config.py` for all configuration
38+
- **Update docstrings** following Google style for any function changes
39+
- **Dependencies must reflect in**:
40+
- Install scripts
41+
- requirements.txt
42+
- **SECURITY UPDATES MANDATORY**
43+
44+
#### 💾 Data Safety
45+
- **CRITICAL**: Backup `data/` before schema changes to:
46+
- knowledge_base.db
47+
- memory_system.db
48+
49+
### 🚀 NPU Worker and Redis Code Search Capabilities
50+
51+
**YOU ARE AUTHORIZED TO USE NPU WORKER AND REDIS FOR ADVANCED CODE ANALYSIS**
52+
53+
#### Available Tools
54+
- `src/agents/npu_code_search_agent.py` - High-performance code searching
55+
- `/api/code_search/` endpoints - Code analysis tasks
56+
- NPU acceleration for semantic code similarity (when hardware supports)
57+
- Redis-based indexing for fast code element lookup
58+
59+
#### 🎯 APPROVED DEVELOPMENT SPEEDUP TASKS
60+
- Code duplicate detection and removal
61+
- Cross-codebase pattern analysis and comparisons
62+
- Semantic code similarity searches
63+
- Function/class dependency mapping
64+
- Import optimization and unused code detection
65+
- Architecture pattern identification
66+
- Code quality consistency analysis
67+
- Dead code elimination assistance
68+
- Refactoring opportunity identification
69+
70+
### 🔐 Secrets Management Requirements
71+
72+
**IMPLEMENT COMPREHENSIVE SECRETS MANAGEMENT SYSTEM**
73+
74+
#### Dual-Scope Architecture
75+
- **Chat-scoped**: Conversation-only secrets
76+
- **General-scoped**: Available across all chats
77+
78+
#### Features Required
79+
- **Multiple input methods**: GUI secrets management tab + chat-based entry
80+
- **Secret types**: SSH keys, passwords, API keys for agent resource access
81+
- **Transfer capability**: Move chat secrets to general pool when needed
82+
- **Cleanup dialogs**: On chat deletion, prompt for secret/file transfer or deletion
83+
- **Security isolation**: Chat secrets only accessible within originating conversation
84+
- **Agent integration**: Seamless access to appropriate secrets based on scope
85+
86+
### 📝 Development Workflow Standards
87+
88+
#### Regular Commit Strategy
89+
**COMMIT EARLY AND OFTEN AFTER VERIFICATION**
90+
- **Commit frequency**: After every logical unit of work (function, fix, feature component)
91+
- **Maximum change threshold**: No more than 50-100 lines per commit unless absolutely necessary
92+
- **Verification before each commit**:
93+
```bash
94+
# 1. Run tests for affected areas
95+
python -m pytest tests/test_relevant_module.py -v
96+
97+
# 2. Lint check
98+
flake8 src/ backend/ --max-line-length=88 --extend-ignore=E203,W503
99+
100+
# 3. Quick functional test
101+
./run_agent.sh --test-mode
102+
103+
# 4. Commit with descriptive message
104+
git add . && git commit -m "type: brief description of change"
105+
```
106+
107+
#### Commit Types & Examples
108+
- `fix: resolve memory leak in NPU worker initialization`
109+
- `feat: add Redis code search indexing capability`
110+
- `test: add unit tests for secrets management`
111+
- `docs: update API documentation for code search endpoints`
112+
- `refactor: extract configuration logic to config.py`
113+
- `security: update dependency versions for CVE fixes`
114+
- `chore: organize test files into tests/ subdirectories`
115+
116+
#### When to Commit
117+
✅ **DO COMMIT**:
118+
- Single function implementation complete
119+
- Bug fix verified and tested
120+
- Configuration change tested
121+
- Documentation update complete
122+
- Test suite addition/modification
123+
- Dependency update with verification
124+
125+
❌ **DON'T COMMIT**:
126+
- Broken or partially working code
127+
- Untested changes
128+
- Mixed unrelated modifications
129+
- Code with linting errors/warnings
130+
- Changes without updated documentation
131+
132+
#### Commit Organization
133+
**ALL COMMITS MUST BE ORGANIZED BY TOPIC AND FUNCTIONALITY**
134+
- Group related changes together in logical sequence
135+
- Provide clear, descriptive commit messages
136+
- Ensure each commit represents a complete, working change
137+
- Avoid mixing unrelated modifications in a single commit
138+
- Separate refactoring, bug fixes, and feature additions into different commits
139+
140+
#### Priority Hierarchy
141+
1. **🔴 Critical Errors** (blocking functionality)
142+
2. **🟡 Warnings** (potential issues)
143+
3. **🔵 Security Updates** (mandatory)
144+
4. **🟢 Features** (new functionality)
145+
5. **⚪ Refactoring** (code improvement)
146+
147+
### 🛠️ Quick Commands Reference
148+
149+
```bash
150+
# Pre-commit quality check
151+
flake8 src/ backend/ --max-line-length=88 --extend-ignore=E203,W503
152+
153+
# Test mode verification
154+
./run_agent.sh --test-mode
155+
156+
# Phase 9 testing
157+
python test_phase9_ai.py
158+
159+
# NPU worker testing
160+
python test_npu_worker.py
161+
162+
# Code search via NPU
163+
python src/agents/npu_code_search_agent.py --query "your_search_query"
164+
```
165+
166+
### 📋 Pre-Deployment Checklist
167+
168+
#### Before Each Commit
169+
- [ ] Tests pass for affected modules
170+
- [ ] Flake8 checks clean
171+
- [ ] Quick functional test completed
172+
- [ ] Changes are logically complete
173+
- [ ] Commit message is descriptive
174+
175+
#### Before Full Deployment
176+
- [ ] All incremental commits verified
177+
- [ ] Integration tests pass
178+
- [ ] Documentation updated
179+
- [ ] Dependencies documented
180+
- [ ] Data backed up (if schema changes)
181+
- [ ] Security review completed
182+
- [ ] All commit messages follow convention
183+
- [ ] Related changes properly sequenced
184+
185+
#### Emergency Rollback Plan
186+
- Each commit is atomic and can be reverted independently
187+
- Critical changes have backup commits before implementation
188+
- Database migrations are reversible
189+
- Configuration changes are documented with previous values
190+
191+
---
192+
193+
**Remember**: Quality and completeness are non-negotiable. Every task started must be completed to production standards.

0 commit comments

Comments
 (0)