Skip to content

Commit 2ab1953

Browse files
Anton-DodonovAnton-Dodonov
committed
https_vpn
1 parent 32acf64 commit 2ab1953

897 files changed

Lines changed: 8291 additions & 50 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/commands/adr.guide.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# ADR Guide - Reference Material
2+
3+
Reference guide for Architecture Decision Records. Use `/adr` for creating and managing ADRs.
4+
5+
## Language-Specific Adaptations
6+
7+
### Rust Projects
8+
9+
**Directory Structure**:
10+
- Place ADRs at workspace root (for multi-crate projects)
11+
- Consider separate ADRs for major crate decisions
12+
- Document `Cargo.toml` feature flag decisions
13+
- Track dependency upgrade rationales
14+
15+
**Common ADR Categories**:
16+
- `performance` - Optimization decisions, benchmarking results
17+
- `safety` - Memory safety, concurrency patterns
18+
- `api-design` - Public API evolution, breaking changes
19+
- `dependencies` - Crate selection, version pinning
20+
- `testing` - Property testing, fuzzing strategies
21+
22+
### Python Projects
23+
24+
**Directory Structure**:
25+
- Compatible with `pyproject.toml` and `setup.py` structures
26+
- Consider ADRs for virtual environment strategies
27+
- Document packaging and distribution decisions
28+
29+
**Common ADR Categories**:
30+
- `packaging` - Distribution, dependency management
31+
- `typing` - Type hints adoption, mypy configuration
32+
- `async` - asyncio patterns, concurrency approaches
33+
- `testing` - pytest strategies, test organization
34+
35+
### JavaScript/TypeScript Projects
36+
37+
**Directory Structure**:
38+
- Works with monorepos (nx, lerna, rush)
39+
- Consider ADRs for build tool decisions
40+
- Document framework migration paths
41+
42+
**Common ADR Categories**:
43+
- `bundling` - Webpack, vite, rollup decisions
44+
- `typing` - TypeScript adoption, configuration
45+
- `state-management` - Redux, zustand, context patterns
46+
- `testing` - Jest, vitest, cypress strategies
47+
48+
### Go Projects
49+
50+
**Directory Structure**:
51+
- Align with Go module structure
52+
- Consider ADRs for package organization
53+
- Document interface design decisions
54+
55+
**Common ADR Categories**:
56+
- `concurrency` - Goroutine patterns, channel usage
57+
- `error-handling` - Error wrapping, custom errors
58+
- `interfaces` - API design, abstraction levels
59+
- `dependencies` - Module selection, vendor strategies
60+
61+
---
62+
63+
## Scaling Considerations
64+
65+
### Small Projects (1-10 ADRs)
66+
- Simple directory structure
67+
- Basic cross-referencing
68+
- Manual index maintenance acceptable
69+
70+
### Medium Projects (10-50 ADRs)
71+
- Category system important for organization
72+
- Regular cleanup of superseded ADRs
73+
74+
### Large Projects (50+ ADRs)
75+
- Advanced tagging and filtering needed
76+
- Consider retention policies for old ADRs
77+
- Search becomes critical
78+
79+
---
80+
81+
## Migration from Legacy ADRs
82+
83+
### Common Legacy Patterns
84+
85+
**Scattered Decision Documents**:
86+
- Design docs in various formats and locations
87+
- Wiki pages with outdated decision rationale
88+
- Comments in code with design explanations
89+
90+
**Duplicate Content**:
91+
- Same information in multiple files/locations
92+
- Different versions of the same document
93+
94+
### Migration Strategy
95+
96+
#### Phase 1: Assessment
97+
```bash
98+
# Inventory existing documentation
99+
find . -name "*.md" | grep -E "(design|decision|architecture|adr)"
100+
101+
# Identify duplicates
102+
find . -name "*.md" -exec basename {} \; | sort | uniq -d
103+
```
104+
105+
#### Phase 2: Triage
106+
- **Keep and Migrate**: Clear architectural choices with rationale
107+
- **Archive**: Old design docs that informed past decisions
108+
- **Consolidate**: Same information in multiple places
109+
- **Discard**: Outdated, superseded, irrelevant
110+
111+
#### Phase 3: Execute
112+
1. Verify before removal (diff files)
113+
2. Check for references to files being moved
114+
3. Update cross-references
115+
4. Document changes
116+
117+
### Safe Migration Process
118+
119+
```bash
120+
# Always verify files are identical before removing
121+
diff file1.md file2.md
122+
123+
# Check for any references
124+
grep -r "file1.md" . --exclude-dir=.git
125+
```
126+
127+
---
128+
129+
## Success Metrics
130+
131+
### Adoption Indicators
132+
- ADRs created for significant decisions
133+
- Regular updates during development
134+
- Reference to ADRs in code reviews
135+
136+
### Quality Indicators
137+
- ADRs contain sufficient context for decision recreation
138+
- Implementation matches documented decisions
139+
- Lessons learned captured
140+
141+
### Value Indicators
142+
- Faster onboarding of new team members
143+
- Reduced re-litigation of past decisions
144+
- Better impact analysis for proposed changes
145+
146+
---
147+
148+
## Integration Points
149+
150+
- **Git Workflows**: git-flow, GitHub Flow, GitLab Flow
151+
- **Issue Tracking**: GitHub Issues, Jira, Linear
152+
- **Code Review**: Reference ADRs in PR descriptions
153+
- **Documentation**: Link from README, architecture docs

‎.claude/commands/adr.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Architecture Decision Records Flow
2+
3+
You are entering ADR (Architecture Decision Records) mode. Read `flows/adr.md` for the complete flow reference.
4+
5+
## Command: $ARGUMENTS
6+
7+
Parse the arguments to determine the action:
8+
9+
### `start [name]` - Start new ADR
10+
1. Read `flows/adr-index.md` to get next ADR number
11+
2. Create directory `flows/adr-[NNN]-[name]/`
12+
3. Copy templates from `flows/.templates/adr/`
13+
4. Create `_status.md` with phase = DRAFT
14+
5. Update `adr-index.md` with new entry
15+
6. Begin drafting decision context with user
16+
17+
### `resume [number-or-name]` - Resume existing ADR
18+
1. Find ADR by number or name in `flows/adr-*/`
19+
2. Read `_status.md` to determine current phase
20+
3. Read all existing artifacts
21+
4. Report current state to user
22+
5. Continue from where left off
23+
24+
### `quick [name]` - Create lightweight ADR
25+
1. Same as `start` but use `lightweight.md` template
26+
2. Simplified for smaller decisions
27+
28+
### `list` - Show all ADRs
29+
1. Read `flows/adr-index.md`
30+
2. Display table: Number | Title | Status | Created
31+
32+
### `status` - Show active ADRs
33+
1. List ADRs in DRAFT or REVIEW phase
34+
2. Show current blockers and next actions
35+
36+
### No arguments or `help`
37+
1. Show available commands
38+
2. Show summary of ADRs by status (draft/review/approved/rejected)
39+
40+
---
41+
42+
## Phase Behaviors
43+
44+
### DRAFT Phase
45+
- Elicit context and decision drivers from user
46+
- Document considered options (minimum 2)
47+
- Analyze pros/cons for each option
48+
- Draft proposed decision
49+
- Document expected consequences
50+
- Update `adr.md` iteratively
51+
- Wait for explicit "ready for review" before advancing
52+
53+
### REVIEW Phase
54+
- Verify all required sections complete
55+
- Ask clarifying questions if needed
56+
- Address reviewer feedback
57+
- Update consequences based on review
58+
- Wait for explicit "ADR approved" or "ADR rejected"
59+
60+
### APPROVED Phase
61+
- Decision is final
62+
- Update `adr-index.md` with decided date
63+
- Link to implementing specs/PRs when available
64+
- Mark any superseded ADRs
65+
66+
### REJECTED Phase
67+
- Document rejection rationale
68+
- Note alternative direction if applicable
69+
- Keep for historical reference
70+
71+
---
72+
73+
## Status Transitions
74+
75+
```
76+
DRAFT ──["ready for review"]──> REVIEW
77+
REVIEW ──["ADR approved"]──> APPROVED
78+
REVIEW ──["ADR rejected"]──> REJECTED
79+
APPROVED ──[new ADR supersedes]──> SUPERSEDED
80+
```
81+
82+
---
83+
84+
## Always
85+
86+
- Update `_status.md` after every significant change
87+
- Update `adr-index.md` when status changes
88+
- Never skip phases or assume approval
89+
- When uncertain, ask rather than assume
90+
- Reference related ADRs and specs
91+
- Keep decision focused (one decision per ADR)

‎.claude/commands/ddd.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Document-Driven Development Flow
2+
3+
You are entering DDD (Document-Driven Development) mode. Read `flows/ddd.md` for the complete flow reference.
4+
5+
**DDD vs SDD**: Use DDD when feature requires stakeholder communication - clients, executives, end users need to understand the value. Final phase creates a **mini-presentation**, not technical docs.
6+
7+
## Command: $ARGUMENTS
8+
9+
Parse the arguments to determine the action:
10+
11+
### `start [name]` - Start new DDD flow
12+
1. Create directory `flows/ddd-[name]/`
13+
2. Copy templates from `flows/.templates/ddd/`
14+
3. Create `_status.md` with phase = REQUIREMENTS
15+
4. Begin requirements elicitation with user
16+
17+
### `resume [name]` - Resume existing flow
18+
1. Read `flows/ddd-[name]/_status.md` to determine current phase
19+
2. Read all existing artifacts in the document dir
20+
3. Report current state to user
21+
4. Continue from where left off
22+
23+
### `fork [existing] [new]` - Fork for context recovery
24+
1. Copy `flows/ddd-[existing]/` to `flows/ddd-[new]/`
25+
2. Update `_status.md` to note the fork origin
26+
3. Ask user what adjustments to make
27+
4. Continue from current phase with modifications
28+
29+
### `status` - Show all active DDD flows
30+
1. List all `flows/ddd-*/` directories
31+
2. Read each `_status.md` and summarize phase + blockers
32+
33+
### No arguments or `help`
34+
1. Show available commands and current active flows
35+
36+
---
37+
38+
## Phase Behaviors
39+
40+
### REQUIREMENTS Phase
41+
- Elicit what user wants to build and why
42+
- Ask clarifying questions
43+
- Document user stories with acceptance criteria
44+
- Identify constraints and non-goals
45+
- Update `01-requirements.md` iteratively
46+
- Wait for explicit "requirements approved" before advancing
47+
48+
### SPECIFICATIONS Phase
49+
- Analyze codebase for affected systems
50+
- Design interfaces and data models
51+
- Document edge cases
52+
- Update `02-specifications.md` iteratively
53+
- Wait for explicit "specs approved" before advancing
54+
55+
### PLAN Phase
56+
- Break specs into atomic tasks
57+
- Identify file changes and dependencies
58+
- Estimate complexity
59+
- Update `03-plan.md` iteratively
60+
- Wait for explicit "plan approved" before advancing
61+
62+
### IMPLEMENTATION Phase
63+
- Execute plan task by task
64+
- Follow CLAUDE.md testing protocol (one test at a time)
65+
- Log progress in `04-implementation-log.md`
66+
- Document any deviations from plan
67+
- Wait for implementation completion before advancing
68+
69+
### DOCUMENTATION Phase - Feature Presentation
70+
71+
**Critical**: This is NOT technical documentation. It's a **mini-presentation** for stakeholders.
72+
73+
**Mindset**: "How do I explain this to a client who will pay for this?"
74+
75+
**README.md structure:**
76+
```markdown
77+
# [Feature] - [One-line value proposition]
78+
79+
## The Problem
80+
[Pain point - stakeholder language]
81+
82+
## The Solution
83+
[How this helps - benefits focus]
84+
85+
## Key Benefits
86+
[Business/user value, not features]
87+
88+
## How It Works (Simple)
89+
[Analogy - grandmother should understand]
90+
91+
## Example Scenario
92+
[Concrete story]
93+
94+
## Getting Started
95+
[3 steps max to value]
96+
```
97+
98+
**Tone**: Value-first, jargon-free, concrete, compelling
99+
100+
- Wait for explicit "docs approved" before marking complete
101+
102+
---
103+
104+
## Always
105+
106+
- Update `_status.md` after every significant change
107+
- Never skip phases or assume approval
108+
- When uncertain, ask rather than assume
109+
- Before ending session, ensure handoff notes are complete
110+
- Remember: Documentation phase is a FEATURE PRESENTATION for stakeholders
111+
- Think "mini-pitch" not "technical docs"
112+
- Lead with value, not features

0 commit comments

Comments
 (0)