refactor(cursor-rules): restructure rules architecture with meta-rule system
- Reorganize cursor rules into logical domain-based directories - Implement meta-rule system for workflow-specific rule bundling - Move core rules to dedicated /core directory - Consolidate development rules under /development namespace - Add architectural patterns and implementation examples - Create workflow-specific meta-rules for common development tasks - Remove deprecated standalone rule files - Update package dependencies for new rule structure BREAKING CHANGE: Cursor rules file structure has been reorganized Files moved from root rules directory to domain-specific subdirectories
This commit is contained in:
285
.cursor/rules/development/time_implementation.mdc
Normal file
285
.cursor/rules/development/time_implementation.mdc
Normal file
@@ -0,0 +1,285 @@
|
||||
# Time Implementation — Technical Instructions
|
||||
|
||||
> **Agent role**: Reference this file for detailed implementation instructions
|
||||
when working with time handling in development.
|
||||
|
||||
## Real-Time Context in Developer Interactions
|
||||
|
||||
- The model must always resolve **"current time"** using the **developer's
|
||||
|
||||
actual system time and timezone**.
|
||||
|
||||
- When generating timestamps (e.g., in investigation logs, ADRs, or examples),
|
||||
|
||||
the model should:
|
||||
|
||||
- Use the **developer's current local time** by default.
|
||||
|
||||
- Indicate the timezone explicitly (e.g., `2025-08-17T10:32-05:00`).
|
||||
|
||||
- Optionally provide UTC alongside if context requires cross-team clarity.
|
||||
|
||||
- When interpreting relative terms like *now*, *today*, *last week*:
|
||||
|
||||
- Resolve them against the **developer's current time**.
|
||||
|
||||
- Convert them into **absolute ISO-8601 values** in the output.
|
||||
|
||||
## LLM Time Checking Instructions
|
||||
|
||||
**CRITICAL**: The LLM must actively query the system for current time rather
|
||||
than assuming or inventing times.
|
||||
|
||||
### How to Check Current Time
|
||||
|
||||
#### 1. **Query System Time (Required)**
|
||||
|
||||
- **Always start** by querying the current system time using available tools
|
||||
|
||||
- **Never assume** what the current time is
|
||||
|
||||
- **Never use** placeholder values like "current time" or "now"
|
||||
|
||||
#### 2. **Available Time Query Methods**
|
||||
|
||||
- **System Clock**: Use `date` command or equivalent system time function
|
||||
|
||||
- **Programming Language**: Use language-specific time functions (e.g.,
|
||||
|
||||
`Date.now()`, `datetime.now()`)
|
||||
|
||||
- **Environment Variables**: Check for time-related environment variables
|
||||
|
||||
- **API Calls**: Use time service APIs if available
|
||||
|
||||
#### 3. **Required Time Information**
|
||||
|
||||
When querying time, always obtain:
|
||||
|
||||
- **Current Date**: YYYY-MM-DD format
|
||||
|
||||
- **Current Time**: HH:MM:SS format (24-hour)
|
||||
|
||||
- **Timezone**: Current system timezone or UTC offset
|
||||
|
||||
- **UTC Equivalent**: Convert local time to UTC for cross-team clarity
|
||||
|
||||
#### 4. **Time Query Examples**
|
||||
|
||||
```bash
|
||||
|
||||
# Example: Query system time
|
||||
|
||||
$ date
|
||||
|
||||
# Expected output: Mon Aug 17 10:32:45 EDT 2025
|
||||
|
||||
# Example: Query UTC time
|
||||
|
||||
$ date -u
|
||||
|
||||
# Expected output: Mon Aug 17 14:32:45 UTC 2025
|
||||
|
||||
```
|
||||
|
||||
```python
|
||||
|
||||
# Example: Python time query
|
||||
|
||||
import datetime
|
||||
current_time = datetime.datetime.now()
|
||||
utc_time = datetime.datetime.utcnow()
|
||||
print(f"Local: {current_time}")
|
||||
print(f"UTC: {utc_time}")
|
||||
|
||||
```
|
||||
|
||||
```javascript
|
||||
|
||||
// Example: JavaScript time query
|
||||
const now = new Date();
|
||||
const utc = new Date().toISOString();
|
||||
console.log(`Local: ${now}`);
|
||||
console.log(`UTC: ${utc}`);
|
||||
|
||||
```
|
||||
|
||||
#### 5. **LLM Time Checking Workflow**
|
||||
|
||||
1. **Query**: Actively query system for current time
|
||||
|
||||
2. **Validate**: Confirm time data is reasonable and current
|
||||
|
||||
3. **Format**: Convert to ISO 8601 format
|
||||
|
||||
4. **Context**: Provide both local and UTC times when helpful
|
||||
|
||||
5. **Document**: Show the source of time information
|
||||
|
||||
#### 6. **Error Handling for Time Queries**
|
||||
|
||||
- **If time query fails**: Ask user for current time or use "unknown time"
|
||||
|
||||
with explanation
|
||||
|
||||
- **If timezone unclear**: Default to UTC and ask for clarification
|
||||
|
||||
- **If time seems wrong**: Verify with user before proceeding
|
||||
|
||||
- **Always log**: Record when and how time was obtained
|
||||
|
||||
#### 7. **Time Query Verification**
|
||||
|
||||
Before using queried time, verify:
|
||||
|
||||
- [ ] Time is recent (within last few minutes)
|
||||
|
||||
- [ ] Timezone information is available
|
||||
|
||||
- [ ] UTC conversion is accurate
|
||||
|
||||
- [ ] Format follows ISO 8601 standard
|
||||
|
||||
## Model Behavior Rules
|
||||
|
||||
- **Never invent a "fake now"**: All "current time" references must come from
|
||||
|
||||
the real system clock available at runtime.
|
||||
|
||||
- **Check developer time zone**: If ambiguous, ask for clarification (e.g.,
|
||||
|
||||
"Should I use UTC or your local timezone?").
|
||||
|
||||
- **Format for clarity**:
|
||||
|
||||
- Local time: `YYYY-MM-DDTHH:mm±hh:mm`
|
||||
|
||||
- UTC equivalent (if needed): `YYYY-MM-DDTHH:mmZ`
|
||||
|
||||
## Technical Implementation Notes
|
||||
|
||||
### UTC Storage Principle
|
||||
|
||||
- **Store all timestamps in UTC** in databases, logs, and serialized formats
|
||||
|
||||
- **Convert to local time only for user display**
|
||||
|
||||
- **Use ISO 8601 format** for all storage: `YYYY-MM-DDTHH:mm:ss.sssZ`
|
||||
|
||||
### Common Implementation Patterns
|
||||
|
||||
#### Database Storage
|
||||
|
||||
```sql
|
||||
|
||||
-- ✅ Good: Store in UTC
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
|
||||
|
||||
```
|
||||
|
||||
#### API Responses
|
||||
|
||||
```json
|
||||
|
||||
// ✅ Good: Include both UTC and local time
|
||||
{
|
||||
"eventTime": "2025-08-17T14:00:00Z",
|
||||
"localTime": "2025-08-17T10:00:00-04:00",
|
||||
"timezone": "America/New_York"
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
#### Logging
|
||||
|
||||
```python
|
||||
|
||||
# ✅ Good: Log in UTC with timezone info
|
||||
|
||||
logger.info(f"User action at {datetime.utcnow().isoformat()}Z (UTC)")
|
||||
|
||||
```
|
||||
|
||||
### Timezone Handling Best Practices
|
||||
|
||||
#### 1. Always Store Timezone Information
|
||||
|
||||
- Include IANA timezone identifier (e.g., `America/New_York`)
|
||||
|
||||
- Store UTC offset at time of creation
|
||||
|
||||
- Handle daylight saving time transitions automatically
|
||||
|
||||
#### 2. User Display Considerations
|
||||
|
||||
- Convert UTC to user's preferred timezone
|
||||
|
||||
- Show timezone abbreviation when helpful
|
||||
|
||||
- Use relative time for recent events ("2 hours ago")
|
||||
|
||||
#### 3. Edge Case Handling
|
||||
|
||||
- **Daylight Saving Time**: Use timezone-aware libraries
|
||||
|
||||
- **Leap Seconds**: Handle gracefully (rare but important)
|
||||
|
||||
- **Invalid Times**: Validate before processing
|
||||
|
||||
### Common Mistakes to Avoid
|
||||
|
||||
#### 1. Timezone Confusion
|
||||
|
||||
- ❌ **Don't**: Assume server timezone is user timezone
|
||||
|
||||
- ✅ **Do**: Always convert UTC to user's local time for display
|
||||
|
||||
#### 2. Format Inconsistency
|
||||
|
||||
- ❌ **Don't**: Mix different time formats in the same system
|
||||
|
||||
- ✅ **Do**: Standardize on ISO 8601 for all storage
|
||||
|
||||
#### 3. Relative Time References
|
||||
|
||||
- ❌ **Don't**: Use relative terms in persistent storage
|
||||
|
||||
- ✅ **Do**: Convert relative terms to absolute timestamps immediately
|
||||
|
||||
---
|
||||
|
||||
**See also**:
|
||||
|
||||
- `.cursor/rules/development/time.mdc` for core principles
|
||||
|
||||
- `.cursor/rules/development/time_examples.mdc` for practical examples
|
||||
|
||||
**Status**: Active implementation guidelines
|
||||
**Priority**: Medium
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: time.mdc
|
||||
**Stakeholders**: Development team, DevOps team
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before Time Implementation
|
||||
|
||||
- [ ] **Time Context**: Understand what time information needs to be implemented
|
||||
- [ ] **Format Review**: Review time formatting standards (UTC, ISO 8601)
|
||||
- [ ] **Platform Check**: Identify platform-specific time requirements
|
||||
- [ ] **User Context**: Consider user's timezone and display preferences
|
||||
|
||||
### During Time Implementation
|
||||
|
||||
- [ ] **UTC Storage**: Use UTC for all system and log timestamps
|
||||
- [ ] **Format Consistency**: Apply consistent time formatting patterns
|
||||
- [ ] **Timezone Handling**: Properly handle timezone conversions
|
||||
- [ ] **User Display**: Format times appropriately for user display
|
||||
|
||||
### After Time Implementation
|
||||
|
||||
- [ ] **Format Validation**: Verify time formats are correct and consistent
|
||||
- [ ] **Cross-Platform Testing**: Test time handling across different platforms
|
||||
- [ ] **Documentation**: Update relevant documentation with time patterns
|
||||
- [ ] **User Experience**: Confirm time display is clear and user-friendly
|
||||
Reference in New Issue
Block a user