mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-11 02:33:51 +08:00
feat: Enhance Code Developer and Requirements Analyst agents with proactive debugging and self-enhancement strategies
This commit is contained in:
catlog22
@@ -99,12 +99,96 @@ For each task in the plan:
|
||||
- Verify integration
|
||||
- Test error cases
|
||||
- Check performance
|
||||
- **If tests fail**: Initiate Debug Workflow (see Debug Workflow section)
|
||||
|
||||
5. **Report Progress**
|
||||
- Update implementation.md
|
||||
- Log any issues or blockers
|
||||
- Note decisions made
|
||||
|
||||
## Debug Workflow
|
||||
|
||||
When tests fail during implementation, the CD agent MUST initiate the hypothesis-driven debug workflow. This workflow systematically identifies and resolves bugs through structured hypothesis testing.
|
||||
|
||||
### Debug Triggers
|
||||
|
||||
| Trigger | Condition | Action |
|
||||
|---------|-----------|--------|
|
||||
| **Test Failure** | Automated tests fail during implementation | Start debug workflow |
|
||||
| **Integration Conflict** | Blockers logged in `issues.md` | Start debug workflow |
|
||||
| **VAS Feedback** | Orchestrator provides validation failure feedback | Start debug workflow |
|
||||
|
||||
### Debug Workflow Phases
|
||||
|
||||
1. **Isolate Failure**
|
||||
- Pinpoint the specific test or condition that is failing
|
||||
- Extract exact error message and stack trace
|
||||
- Identify the failing component/function
|
||||
|
||||
2. **Formulate Hypothesis**
|
||||
- Generate a specific, testable hypothesis about the root cause
|
||||
- Example: "Error is caused by null value passed from function X"
|
||||
- Log hypothesis in `debug-log.ndjson`
|
||||
- Prioritize hypotheses based on: error messages > recent changes > dependency relationships > edge cases
|
||||
|
||||
3. **Design Experiment**
|
||||
- Determine minimal change to test hypothesis
|
||||
- Options: add logging, create minimal unit test, inspect variable, add breakpoint
|
||||
- Document experiment design
|
||||
|
||||
4. **Execute & Observe**
|
||||
- Apply the change and run the test
|
||||
- Capture inputs, actions taken, and observed outcomes
|
||||
- Log structured results in `debug-log.ndjson`
|
||||
|
||||
5. **Analyze & Conclude**
|
||||
- Compare outcome to hypothesis
|
||||
- If **confirmed**: Proceed to implement fix (Phase 6)
|
||||
- If **refuted**: Log finding and formulate new hypothesis (return to Phase 2)
|
||||
- If **inconclusive**: Refine experiment and repeat
|
||||
|
||||
6. **Implement Fix**
|
||||
- Once root cause confirmed, implement necessary code changes
|
||||
- Document fix rationale in implementation.md
|
||||
- Log fix in code-changes.log
|
||||
|
||||
7. **Verify Fix**
|
||||
- Run all relevant tests to ensure fix is effective
|
||||
- Verify no regressions introduced
|
||||
- Mark issue as resolved in issues.md
|
||||
|
||||
### Debug Log Format (NDJSON)
|
||||
|
||||
File: `.workflow/.cycle/{cycleId}.progress/cd/debug-log.ndjson`
|
||||
|
||||
Schema:
|
||||
```json
|
||||
{
|
||||
"timestamp": "2026-01-23T10:00:00+08:00",
|
||||
"iteration": 1,
|
||||
"issue_id": "BUG-001",
|
||||
"file": "src/auth/oauth.ts",
|
||||
"hypothesis": "OAuth token refresh fails due to expired refresh_token not handled",
|
||||
"action": "Added logging to capture refresh_token expiry",
|
||||
"observation": "Refresh token is expired but code doesn't check expiry before use",
|
||||
"outcome": "confirmed"
|
||||
}
|
||||
```
|
||||
|
||||
Outcome values: `confirmed | refuted | inconclusive`
|
||||
|
||||
### Hypothesis Priority Order
|
||||
|
||||
1. **Direct Error Messages/Stack Traces**: Most reliable starting point
|
||||
2. **Recent Changes**: Check `code-changes.log` for recent modifications
|
||||
3. **Dependency Relationships**: Analyze relationships between failing component and its dependencies
|
||||
4. **Edge Cases**: Review `edge-cases.md` for documented edge cases
|
||||
|
||||
### Output
|
||||
|
||||
Debug workflow generates an additional file:
|
||||
- **debug-log.ndjson**: NDJSON log of all hypothesis-test cycles
|
||||
|
||||
### Phase 3: Output
|
||||
|
||||
Generate files in `.workflow/.cycle/{cycleId}.progress/cd/`:
|
||||
@@ -190,11 +274,12 @@ Overview of what was implemented in this iteration.
|
||||
PHASE_RESULT:
|
||||
- phase: cd
|
||||
- status: success | failed | partial
|
||||
- files_written: [implementation.md, code-changes.log, issues.md]
|
||||
- files_written: [implementation.md, code-changes.log, debug-log.ndjson (if debug executed), issues.md]
|
||||
- summary: N tasks completed, M files modified, X blockers identified
|
||||
- tasks_completed: N
|
||||
- files_modified: M
|
||||
- tests_passing: X/Y
|
||||
- debug_cycles: Z (if debug executed)
|
||||
- blockers: []
|
||||
- issues: [list of open issues]
|
||||
```
|
||||
|
||||
@@ -59,13 +59,24 @@ The Requirements Analyst maintains **a single file** (`requirements.md`) contain
|
||||
- Task description from state
|
||||
- Project tech stack and guidelines
|
||||
|
||||
2. **Analyze Requirements**
|
||||
- Functional requirements
|
||||
- Non-functional requirements
|
||||
2. **Analyze Explicit Requirements**
|
||||
- Functional requirements from user task
|
||||
- Non-functional requirements (explicit)
|
||||
- Constraints and assumptions
|
||||
- Edge cases
|
||||
|
||||
3. **Generate Single File**
|
||||
3. **Proactive Enhancement** (NEW - Self-Enhancement Phase)
|
||||
- Execute enhancement strategies based on triggers
|
||||
- Scan codebase for implied requirements
|
||||
- Analyze peer agent outputs (EP, CD, VAS from previous iteration)
|
||||
- Suggest associated features and NFR scaffolding
|
||||
|
||||
4. **Consolidate & Finalize**
|
||||
- Merge explicit requirements with proactively generated ones
|
||||
- Mark enhanced items with "(ENHANCED v1.0.0 by RA)"
|
||||
- Add optional "## Proactive Enhancements" section with justification
|
||||
|
||||
5. **Generate Single File**
|
||||
- Write `requirements.md` v1.0.0
|
||||
- Include all sections in one document
|
||||
- Add version header
|
||||
@@ -283,3 +294,77 @@ appendNDJSON('changes.log', {
|
||||
5. **Audit Trail**: Changes.log tracks every modification
|
||||
6. **Readability First**: File should be clear and concise
|
||||
7. **Version Markers**: Mark new items with "(NEW v1.x.0)"
|
||||
8. **Proactive Enhancement**: Always apply self-enhancement phase
|
||||
|
||||
## Self-Enhancement Mechanism
|
||||
|
||||
The RA agent proactively extends requirements based on context analysis.
|
||||
|
||||
### Enhancement Triggers
|
||||
|
||||
| Trigger | Condition | Action |
|
||||
|---------|-----------|--------|
|
||||
| **Initial Analysis** | First iteration (v1.0.0) | Expand vague or high-level requests |
|
||||
| **Implicit Context** | Key config files detected (package.json, Dockerfile, CI config) | Infer NFRs and constraints |
|
||||
| **Cross-Agent Feedback** | Previous iteration has `exploration.identified_risks`, `cd.blockers`, or `vas.test_results.failed_tests` | Cover uncovered requirements |
|
||||
|
||||
### Enhancement Strategies
|
||||
|
||||
1. **Codebase Analysis**
|
||||
- Scan key project files (package.json, Dockerfile, CI/CD configs)
|
||||
- Infer technological constraints and dependencies
|
||||
- Identify operational requirements
|
||||
- Example: Detecting `storybook` dependency → suggest component-driven UI process
|
||||
|
||||
2. **Peer Output Mining**
|
||||
- Analyze EP agent's `exploration.architecture_summary`
|
||||
- Review CD agent's blockers and issues
|
||||
- Examine VAS agent's `test_results.failed_tests`
|
||||
- Formalize insights as new requirements
|
||||
|
||||
3. **Common Feature Association**
|
||||
- Based on functional requirements, suggest associated features
|
||||
- Example: "build user login" → suggest "password reset", "MFA"
|
||||
- Mark as enhancement candidates for user confirmation
|
||||
|
||||
4. **NFR Scaffolding**
|
||||
- For each major functional requirement, add standard NFRs
|
||||
- Categories: Performance, Security, Scalability, Accessibility
|
||||
- Set initial values as "TBD" to ensure consideration
|
||||
|
||||
### Output Format for Enhanced Requirements
|
||||
|
||||
Enhanced requirements are integrated directly into `requirements.md`:
|
||||
|
||||
```markdown
|
||||
## Functional Requirements
|
||||
|
||||
### FR-001: OAuth Authentication
|
||||
User can authenticate via OAuth providers.
|
||||
**Status**: Defined (v1.0.0)
|
||||
**Priority**: High
|
||||
|
||||
### FR-002: Password Reset (ENHANCED v1.0.0 by RA)
|
||||
Users can reset their password via email link.
|
||||
**Status**: Enhanced (auto-suggested)
|
||||
**Priority**: Medium
|
||||
**Trigger**: Common Feature Association (FR-001 → password reset)
|
||||
|
||||
---
|
||||
|
||||
## Proactive Enhancements
|
||||
|
||||
This section documents auto-generated requirements by the RA agent.
|
||||
|
||||
| ID | Trigger | Strategy | Justification |
|
||||
|----|---------|----------|---------------|
|
||||
| FR-002 | FR-001 requires login | Common Feature Association | Standard auth feature set |
|
||||
| NFR-003 | package.json has `jest` | Codebase Analysis | Test framework implies testability NFR |
|
||||
```
|
||||
|
||||
### Integration Notes
|
||||
|
||||
- Self-enhancement is **internal to RA agent** - no orchestrator changes needed
|
||||
- Read-only access to codebase and cycle state required
|
||||
- Enhanced requirements are **transparently marked** for user review
|
||||
- User can accept, modify, or reject enhanced requirements in next iteration
|
||||
|
||||
Reference in New Issue
Block a user