fix architect agent
This commit is contained in:
王性驊
parent
e36f0c15cd
commit
94f4d77a13
|
|
@ -194,10 +194,13 @@ Add explicit detail for these when relevant:
|
|||
|
||||
| Stage | Action | Input | Output (STRICT PATH) | Skill/Tool |
|
||||
|-------|--------|-------|----------------------|-----------|
|
||||
| 1. Architecture Research | Research technical landscape, existing systems, and comparable architectures | `docs/prd/{feature}.md` | `docs/research/{date}-{topic}-architecture.md` | `architecture-research` |
|
||||
| 2. Analyze PRD | Extract architectural requirements, identify relevant knowledge domains, flag ambiguities | `docs/prd/{feature}.md` + optional `docs/research/{date}-{topic}-architecture.md` | `docs/architecture/{date}-{feature}-analysis.md` | `analyze-prd` |
|
||||
| 3. Design Architecture | Design complete system architecture based on PRD and analysis | `docs/prd/{feature}.md` + optional `docs/architecture/{date}-{feature}-analysis.md` + optional `docs/research/{date}-{topic}-architecture.md` | `docs/architecture/{feature}.md` | `design-architecture` |
|
||||
| 4. Challenge Architecture | Stress-test architecture decisions, validate traceability, detect over/under-engineering | `docs/architecture/{feature}.md` + `docs/prd/{feature}.md` | Updated `docs/architecture/{feature}.md` | `challenge-architecture` |
|
||||
| 1. Analyze Context | Extract architectural requirements, detect ambiguity, identify relevant knowledge domains | `docs/prd/{date}-{feature}.md` | Internal analysis only (no file) | `analyze-prd` |
|
||||
| 2. Design Architecture | Design complete system architecture based on PRD | `docs/prd/{date}-{feature}.md` | `docs/architecture/{date}-{feature}.md` | `design-architecture` |
|
||||
| 3. Challenge Architecture | Stress-test architecture decisions, validate traceability, detect over/under-engineering | `docs/architecture/{date}-{feature}.md` + `docs/prd/{date}-{feature}.md` | Updated `docs/architecture/{date}-{feature}.md` | `challenge-architecture` |
|
||||
|
||||
### Optional Pre-Work
|
||||
|
||||
Before the strict pipeline, the architect may optionally invoke `architecture-research` to investigate technical landscape. This research is internal analysis only and MUST NOT produce artifacts outside the strict output path.
|
||||
|
||||
### Knowledge Contracts
|
||||
|
||||
|
|
@ -215,8 +218,13 @@ The `design-architecture` skill references knowledge contracts during design as
|
|||
| Error Model Design | `error-model-design` | When defining error handling |
|
||||
| Idempotency Design | `idempotency-design` | When designing idempotent operations |
|
||||
|
||||
## Handoff Rule
|
||||
|
||||
Planner reads only `docs/architecture/{date}-{feature}.md`.
|
||||
Architect MUST NOT produce intermediate files that could be mistaken for handoff artifacts.
|
||||
|
||||
## Key Deliverables
|
||||
- [ ] **Architecture Document**:
|
||||
- [ ] **Architecture Document** (strict path: `docs/architecture/{date}-{feature}.md`):
|
||||
- System overview with component diagram (text or ASCII)
|
||||
- Frontend architecture (or N/A with reason)
|
||||
- Backend architecture with service/module boundaries
|
||||
|
|
@ -226,4 +234,4 @@ The `design-architecture` skill references knowledge contracts during design as
|
|||
- Async model (or N/A with reason)
|
||||
- Error model with categories and propagation strategy
|
||||
- Idempotency design (or N/A with reason)
|
||||
- Architectural decision records (Path: `docs/architecture/`)
|
||||
- Architectural decision records
|
||||
|
|
@ -1,15 +1,19 @@
|
|||
---
|
||||
name: analyze-prd
|
||||
description: "Extract architectural requirements from a PRD, identify relevant knowledge domains, and flag ambiguities before architecture design. This is the Architect pipeline's second step, comparable to brainstorming in the PM pipeline."
|
||||
description: "Extract architectural requirements from a PRD, identify relevant knowledge domains, and flag ambiguities before architecture design. This is the Architect pipeline's first step. Produces internal analysis only — no file artifacts."
|
||||
---
|
||||
|
||||
This skill will be invoked after architecture research is complete or when the architect needs to extract architectural requirements from a PRD before starting design.
|
||||
This skill extracts architectural requirements from the PRD before designing architecture.
|
||||
|
||||
**Announce at start:** "I'm using the analyze-prd skill to extract architectural requirements from the PRD."
|
||||
|
||||
## Purpose
|
||||
|
||||
Read the PRD and extract the architectural dimensions that must be addressed during design. Identify which knowledge domains are relevant, flag ambiguities that block architectural decisions, and produce a structured analysis that feeds into `design-architecture`.
|
||||
Read the PRD and extract the architectural dimensions that must be addressed during design. Identify which knowledge domains are relevant, flag ambiguities that block architectural decisions, and produce structured internal analysis that feeds into `design-architecture`.
|
||||
|
||||
## Important
|
||||
|
||||
This skill produces **internal analysis only**. It MUST NOT write any file artifacts. The strict pipeline output is `docs/architecture/{date}-{feature}.md` only.
|
||||
|
||||
## Hard Gate
|
||||
|
||||
|
|
@ -19,8 +23,8 @@ Do NOT start designing architecture in this skill. This skill only extracts and
|
|||
|
||||
You MUST complete these steps in order:
|
||||
|
||||
1. **Read the PRD** at `docs/prd/{feature}.md` end-to-end
|
||||
2. **Read optional research brief** at `docs/research/{date}-{topic}-architecture.md` if it exists
|
||||
1. **Read the PRD** at `docs/prd/{date}-{feature}.md` end-to-end
|
||||
2. **Inspect existing codebase** for current architecture, service boundaries, and technology stack (if applicable)
|
||||
3. **Extract functional requirements** - List each functional requirement and its architectural implications
|
||||
4. **Extract non-functional requirements** - List each NFR and its architectural implications
|
||||
5. **Identify relevant knowledge domains** - Determine which of the 9 knowledge domains are relevant:
|
||||
|
|
@ -35,37 +39,26 @@ You MUST complete these steps in order:
|
|||
- Idempotency Design
|
||||
6. **Flag ambiguities** - Identify any PRD requirements that are unclear for architectural purposes
|
||||
7. **Map requirements to architecture sections** - Show which PRD requirements map to which architecture output sections
|
||||
8. **Write analysis document** - Save to `docs/architecture/{date}-{feature}-analysis.md`
|
||||
|
||||
## Analysis Output Format
|
||||
## Analysis Format
|
||||
|
||||
Save the analysis document to `docs/architecture/{date}-{feature}-analysis.md`.
|
||||
Retain this analysis internally. Do not write it to a file.
|
||||
|
||||
```markdown
|
||||
## PRD Source
|
||||
|
||||
Reference to the PRD file being analyzed.
|
||||
|
||||
## Functional Requirements Extraction
|
||||
|
||||
For each functional requirement in the PRD:
|
||||
|
||||
| # | Requirement | Architectural Implications | Relevant Domains |
|
||||
|---|-------------|---------------------------|-----------------|
|
||||
| FR-1 | ... | ... | system-decomposition, api-contract-design |
|
||||
|
||||
## Non-Functional Requirements Extraction
|
||||
|
||||
For each NFR in the PRD:
|
||||
|
||||
| # | Requirement | Architectural Implications | Relevant Domains |
|
||||
|---|-------------|---------------------------|-----------------|
|
||||
| NFR-1 | ... | ... | storage-knowledge, async-queue-design |
|
||||
|
||||
## Knowledge Domain Relevance
|
||||
|
||||
For each of the 9 knowledge domains, state whether it is relevant and why:
|
||||
|
||||
| Domain | Relevant? | Reason |
|
||||
|--------|-----------|--------|
|
||||
| System Decomposition | Yes/No | ... |
|
||||
|
|
@ -79,7 +72,6 @@ For each of the 9 knowledge domains, state whether it is relevant and why:
|
|||
| Idempotency Design | Yes/No | ... |
|
||||
|
||||
## Requirement-to-Section Mapping
|
||||
|
||||
| Architecture Section | PRD Requirements Served |
|
||||
|---------------------|------------------------|
|
||||
| System Overview | ... |
|
||||
|
|
@ -93,26 +85,20 @@ For each of the 9 knowledge domains, state whether it is relevant and why:
|
|||
| Idempotency Design | ... |
|
||||
|
||||
## Ambiguities And Gaps
|
||||
|
||||
List any PRD requirements that are unclear for architectural purposes and need PM clarification before design can proceed. If none, write "None identified."
|
||||
|
||||
## Research Brief Integration
|
||||
|
||||
If a research brief exists, summarize key findings that inform this analysis. If no research brief exists, write "No architecture research brief available."
|
||||
```
|
||||
|
||||
## Primary Inputs
|
||||
## Primary Input
|
||||
|
||||
- `docs/prd/{feature}.md` (required)
|
||||
- `docs/research/{date}-{topic}-architecture.md` (optional)
|
||||
- `docs/prd/{date}-{feature}.md` (required)
|
||||
|
||||
## Primary Output
|
||||
## Output
|
||||
|
||||
- `docs/architecture/{date}-{feature}-analysis.md`
|
||||
Internal analysis only. No file artifact. Findings are carried forward in memory to inform `design-architecture`.
|
||||
|
||||
## Transition
|
||||
|
||||
After completing this analysis, invoke `design-architecture` with the PRD and analysis document as inputs.
|
||||
After completing this internal analysis, proceed to `design-architecture` with the PRD and analysis findings in memory.
|
||||
|
||||
## Guardrails
|
||||
|
||||
|
|
@ -129,4 +115,5 @@ Do not:
|
|||
- Make technology selections
|
||||
- Define API contracts, schemas, or service boundaries
|
||||
- Write architecture decisions
|
||||
- Produce any architecture output sections
|
||||
- Produce any file artifacts
|
||||
- Write any file to disk
|
||||
|
|
@ -1,9 +1,13 @@
|
|||
---
|
||||
name: architecture-research
|
||||
description: "Research technical landscape, existing system constraints, and comparable system architectures before designing architecture. This is the Architect pipeline's first step, comparable to market-research in the PM pipeline."
|
||||
description: "Optional pre-work for investigating technical landscape, existing system constraints, and comparable architectures before the strict Architect pipeline begins. This skill produces internal analysis only — no file artifacts."
|
||||
---
|
||||
|
||||
Use this skill when the PRD involves significant technical constraints, integration requirements, or architectural decisions that benefit from technical landscape understanding before design begins.
|
||||
This is optional pre-work, not part of the strict Architect pipeline. It is invoked before `analyze-prd` when the PRD involves significant technical constraints that benefit from landscape understanding.
|
||||
|
||||
## Important
|
||||
|
||||
This skill produces **internal analysis only**. It MUST NOT write any file artifacts. The strict pipeline output is `docs/architecture/{date}-{feature}.md` only.
|
||||
|
||||
## Goals
|
||||
|
||||
|
|
@ -29,57 +33,20 @@ Use research to answer:
|
|||
- Do not produce architecture decisions or recommendations
|
||||
- Do not write code, schemas, or API definitions
|
||||
- Do not break down tasks or create milestones
|
||||
- Do not produce file artifacts
|
||||
|
||||
## Process
|
||||
|
||||
1. Read the PRD file at `docs/prd/{feature}.md` to understand requirements
|
||||
1. Read the PRD file at `docs/prd/{date}-{feature}.md` to understand requirements
|
||||
2. Inspect the existing codebase for current architecture, service boundaries, and technology stack
|
||||
3. Identify technical constraints and integration dependencies from the PRD and codebase
|
||||
4. Research comparable system architectures and proven patterns for this problem domain
|
||||
5. Catalog technology options with trade-offs relevant to the PRD requirements
|
||||
6. Write a concise research brief
|
||||
6. Retain findings as internal analysis to inform `analyze-prd` and `design-architecture`
|
||||
|
||||
## Output
|
||||
|
||||
Save research briefs to `docs/research/{date}-{topic}-architecture.md`.
|
||||
|
||||
This file is an input artifact for downstream Architect stages:
|
||||
- `analyze-prd` may use it to identify architectural requirements and constraints
|
||||
- `design-architecture` may use it to inform pattern selection and technology decisions
|
||||
|
||||
Use this format:
|
||||
|
||||
## Research Question
|
||||
|
||||
What architectural question or constraint is being investigated?
|
||||
|
||||
## Existing System Context
|
||||
|
||||
Current service boundaries, data flow, technology stack, and constraints discovered from codebase inspection.
|
||||
|
||||
## Comparable Architectures
|
||||
|
||||
How similar problems have been solved, what patterns succeeded, what patterns failed, and why.
|
||||
|
||||
## Technical Constraints
|
||||
|
||||
Latency, scale, compliance, integration, and infrastructure constraints that bound the design space.
|
||||
|
||||
## Technology Options
|
||||
|
||||
Candidate technologies or approaches with trade-offs relevant to this use case. Present options, not decisions.
|
||||
|
||||
## Risks And Trade-offs
|
||||
|
||||
Technical risks, unknowns, and trade-offs the architect must resolve during design.
|
||||
|
||||
## Implications For Architecture
|
||||
|
||||
What this research means for architectural decisions the architect will make.
|
||||
|
||||
## Sources
|
||||
|
||||
References, documentation, and evidence supporting the findings.
|
||||
This skill produces **internal analysis only**. Findings are carried forward in memory to inform the next pipeline steps. No file is written.
|
||||
|
||||
## Guidance
|
||||
|
||||
|
|
@ -87,4 +54,4 @@ References, documentation, and evidence supporting the findings.
|
|||
- Prefer 3-5 proven patterns over 20 theoretical possibilities
|
||||
- Call out confidence level when evidence is weak
|
||||
- Tie findings back to specific PRD requirements and NFRs
|
||||
- Do not make architecture decisions in this document; that belongs in `design-architecture`
|
||||
- Do not make architecture decisions; that belongs in `design-architecture`
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: challenge-architecture
|
||||
description: "Stress-test architecture decisions, check PRD traceability, detect over-engineering, and validate storage and pattern selections. Comparable to grill-me in the PM pipeline."
|
||||
description: "Stress-test architecture decisions, check PRD traceability, detect over-engineering, and validate storage and pattern selections. Comparable to grill-me in the PM pipeline. Updates the single architecture file in place."
|
||||
---
|
||||
|
||||
Interview the architect relentlessly about every aspect of this architecture until it passes quality gates. Walk down each branch of the architecture decision tree, validating traceability, necessity, and soundness one-by-one.
|
||||
|
|
@ -13,12 +13,14 @@ Ask the questions one at a time.
|
|||
|
||||
## Primary Input
|
||||
|
||||
- `docs/architecture/{feature}.md`
|
||||
- `docs/prd/{feature}.md`
|
||||
- `docs/architecture/{date}-{feature}.md`
|
||||
- `docs/prd/{date}-{feature}.md`
|
||||
|
||||
## Primary Output
|
||||
## Primary Output (STRICT PATH)
|
||||
|
||||
- Updated `docs/architecture/{feature}.md`
|
||||
- Updated `docs/architecture/{date}-{feature}.md`
|
||||
|
||||
This is the **only** file artifact in the Architect pipeline. Challenge results are applied directly to this file. No intermediate files are written.
|
||||
|
||||
## Process
|
||||
|
||||
|
|
@ -158,7 +160,7 @@ After challenging, verify the architecture satisfies:
|
|||
For each issue found:
|
||||
1. Document the issue
|
||||
2. Propose a fix
|
||||
3. Apply the fix to the architecture document
|
||||
3. Apply the fix directly to `docs/architecture/{date}-{feature}.md`
|
||||
4. Re-verify the fix against the PRD
|
||||
|
||||
After all issues are resolved, the architecture is ready for handoff to the Planner.
|
||||
|
|
@ -172,10 +174,12 @@ Do:
|
|||
- Validate traceability to PRD requirements
|
||||
- Detect over-engineering and under-engineering
|
||||
- Propose specific fixes for identified issues
|
||||
- Apply fixes directly to `docs/architecture/{date}-{feature}.md`
|
||||
|
||||
Do not:
|
||||
- Change PRD requirements or scope
|
||||
- Design architecture from scratch
|
||||
- Make implementation-level decisions
|
||||
- Break down tasks or create milestones
|
||||
- Write test cases
|
||||
- Write test cases
|
||||
- Produce any file artifact other than `docs/architecture/{date}-{feature}.md`
|
||||
|
|
@ -1,23 +1,23 @@
|
|||
---
|
||||
name: design-architecture
|
||||
description: "Design system architecture based on PRD requirements and analysis. This is the Architect pipeline's core step, comparable to write-a-prd in the PM pipeline. Produces the complete architecture document."
|
||||
description: "Design system architecture based on PRD requirements. This is the Architect pipeline's core step, producing the single strict output file. Comparable to write-a-prd in the PM pipeline."
|
||||
---
|
||||
|
||||
This skill produces the complete architecture document for a feature.
|
||||
|
||||
**Announce at start:** "I'm using the design-architecture skill to design the system architecture."
|
||||
|
||||
## Primary Inputs
|
||||
## Primary Input
|
||||
|
||||
- `docs/prd/{feature}.md` (required)
|
||||
- `docs/architecture/{date}-{feature}-analysis.md` (from analyze-prd, optional)
|
||||
- `docs/research/{date}-{topic}-architecture.md` (from architecture-research, optional)
|
||||
- `docs/prd/{date}-{feature}.md` (required)
|
||||
|
||||
## Primary Output
|
||||
## Primary Output (STRICT PATH)
|
||||
|
||||
- `docs/architecture/{feature}.md`
|
||||
- `docs/architecture/{date}-{feature}.md`
|
||||
|
||||
**Save architecture to:** `docs/architecture/{feature}.md`
|
||||
This is the **only** file artifact produced by the Architect pipeline. No intermediate files (research, analysis) are written to disk.
|
||||
|
||||
**Save architecture to:** `docs/architecture/{date}-{feature}.md`
|
||||
- (User preferences for architecture location override this default)
|
||||
|
||||
## Hard Gate
|
||||
|
|
@ -28,11 +28,10 @@ Do NOT start this skill if the PRD has unresolved ambiguities that block archite
|
|||
|
||||
You MUST complete these steps in order:
|
||||
|
||||
1. **Read the PRD** end-to-end to understand all requirements
|
||||
2. **Read the analysis document** if available, to understand which knowledge domains are relevant
|
||||
3. **Read the research brief** if available, to inform technology and pattern selections
|
||||
4. **Design each architecture section** based on PRD requirements and relevant knowledge domains
|
||||
5. **Apply knowledge domains** as needed - reference relevant knowledge contracts during design:
|
||||
1. **Read the PRD** at `docs/prd/{date}-{feature}.md` end-to-end to understand all requirements
|
||||
2. **Apply internal analysis** from the `analyze-prd` step (if performed) to understand which knowledge domains are relevant
|
||||
3. **Design each architecture section** based on PRD requirements and relevant knowledge domains
|
||||
4. **Apply knowledge domains** as needed - reference relevant knowledge contracts during design:
|
||||
- `system-decomposition` when designing service boundaries
|
||||
- `api-contract-design` when defining API contracts
|
||||
- `data-modeling` when designing database schema
|
||||
|
|
@ -42,9 +41,9 @@ You MUST complete these steps in order:
|
|||
- `async-queue-design` when designing asynchronous workflows
|
||||
- `error-model-design` when defining error handling
|
||||
- `idempotency-design` when designing idempotent operations
|
||||
6. **Ensure traceability** - every architectural decision must trace back to at least one PRD requirement
|
||||
7. **Write completeness check** - verify all required sections are present and substantive
|
||||
8. **Write the architecture document** to `docs/architecture/{feature}.md`
|
||||
5. **Ensure traceability** - every architectural decision must trace back to at least one PRD requirement
|
||||
6. **Write completeness check** - verify all required sections are present and substantive
|
||||
7. **Write the architecture document** to `docs/architecture/{date}-{feature}.md`
|
||||
|
||||
## Architecture Document Template
|
||||
|
||||
|
|
@ -249,6 +248,7 @@ Do not:
|
|||
- Write implementation code or pseudocode
|
||||
- Choose specific libraries or frameworks at the implementation level
|
||||
- Prescribe code patterns, class structures, or function-level logic
|
||||
- Produce any file artifact other than `docs/architecture/{date}-{feature}.md`
|
||||
|
||||
The Architect defines HOW the system is structured.
|
||||
The Engineering defines HOW the code is written.
|
||||
|
|
|
|||
Loading…
Reference in New Issue