Project 1: “The Personalized Kiro Config” — Configuration Management

Attribute	Value
File	KIRO_CLI_MASTERY.md
Main Programming Language	JSON / Markdown
Coolness Level	Level 2: Practical but Forgettable
Business Potential	1. The “Resume Gold” (Efficiency)
Difficulty	Level 1: Beginner
Knowledge Area	Configuration Management

What you’ll build: A robust, shareable global configuration system for Kiro that defines preferred models, telemetry, and your first global steering rules.

Why it teaches Config: You will understand precedence (global vs project vs agent) and how to persist your preferences across sessions.

Core challenges you’ll face:

• Understanding the JSON schema for settings.json.
• Defining global steering that applies to all projects.
• Resolving conflicts between global and local settings.

Success criteria:

• Kiro uses your chosen default model in new sessions.
• A global steering rule is consistently applied.

---

Real World Outcome

You’ll have a fully configured Kiro CLI installation with persistent preferences that work across all your projects. When you run kiro chat, you’ll see:

Example Output:

$ kiro chat

Kiro CLI v1.4.2 (using claude-sonnet-4 by default)
Session: 2025-01-02-config-test
Telemetry: disabled
Knowledge Base: enabled

You: "Show me my current settings"

Kiro: [reads ~/.config/kiro/settings.json]
  Current configuration:
  - Default model: claude-sonnet-4
  - Telemetry: disabled
  - Auto-compact: enabled (at 80% context)
  - Knowledge base: enabled for *.py, *.js, *.md
  - Global steering: loaded from ~/.kiro/steering/tech.md

You: "Create a new Python function"

Kiro: [applies global steering from tech.md]
  Following your global steering rules:
  - Using type hints for all parameters
  - Including docstrings with examples
  - Following PEP 8 style guide

  Here's the function...

Your settings file at ~/.config/kiro/settings.json will look like this:

{
  "chat": {
    "defaultModel": "claude-sonnet-4",
    "greeting": {
      "enabled": false
    },
    "enableKnowledge": true
  },
  "telemetry": {
    "enabled": false
  },
  "context": {
    "autoCompact": {
      "enabled": true,
      "threshold": 0.8
    }
  },
  "knowledge": {
    "defaultIncludePatterns": ["*.py", "*.js", "*.md", "*.txt"]
  }
}

---

The Core Question You’re Answering

“How do I make Kiro remember my preferences across projects and sessions without repeating myself every time?”

Before building this, think about: Most developers waste time re-configuring tools for every project. Kiro’s three-tier configuration system (global → project → agent) lets you define intelligent defaults once, then override only what’s specific. This project teaches you how to architect reusable AI behavior.

---

Concepts You Must Understand First

Stop and research these before coding:

1. Configuration Hierarchy
   • What happens when global settings conflict with project settings?
   • How does Kiro resolve precedence (global < project < agent)?
   • Where does each config file live in the filesystem?
   • Book Reference: “The Pragmatic Programmer” by Hunt & Thomas - Ch. 8 (Pragmatic Projects)
2. JSON Schema Validation
   • What is the valid structure for settings.json?
   • How do you validate your config before Kiro loads it?
   • What happens when you provide invalid JSON?
   • Book Reference: “Working Effectively with Legacy Code” by Feathers - Ch. 10 (Configuration)
3. Steering Files
   • How do steering files (.md) get loaded into context?
   • What’s the difference between prompt and steering?
   • When should constraints go in config vs steering?
   • Book Reference: “Clean Code” by Martin - Ch. 17 (Smells and Heuristics)

---

Questions to Guide Your Design

Before implementing, think through these:

1. Default Model Selection
   • Which model should be your default: Haiku (fast), Sonnet (balanced), or Opus (powerful)?
   • What tasks will you do most often? (code review vs generation vs complex reasoning)
   • How much do credit costs matter to your workflow?
2. Telemetry and Privacy
   • Do you want Kiro to send usage data to AWS?
   • What are the tradeoffs between telemetry off vs debugging help?
   • Should different projects have different telemetry settings?
3. Knowledge Base Patterns
   • Which file types contain important context for your work?
   • Should you exclude generated files (build/, node_modules/)?
   • How large is your average codebase (affects knowledge base indexing)?

---

Thinking Exercise

Exercise: Trace Configuration Loading

Before creating your config, manually trace how Kiro would load settings for this scenario:

# File structure:
~/.config/kiro/settings.json         → defaultModel: "claude-sonnet-4"
~/my-project/.kiro/settings.json     → defaultModel: "claude-haiku-4"
~/my-project/.kiro/agents/audit.json → model: "claude-opus-4"

# Commands:
1. cd ~/my-project && kiro chat
2. kiro chat --agent audit

Questions while tracing:

• What model is used for command #1? Why?
• What model is used for command #2? Why?
• How would you verify your answer without running the commands?
• What if audit.json didn’t specify a model field?

---

The Interview Questions They’ll Ask

1. “Explain the difference between Kiro’s global, project, and agent configuration levels.”
2. “How would you debug why Kiro isn’t using your preferred model?”
3. “What’s the purpose of the knowledge base feature, and when should you enable it?”
4. “How do steering files differ from agent prompts?”
5. “What are the security implications of enabling telemetry in a corporate environment?”
6. “How would you share configuration across a team without committing credentials?”

---

Hints in Layers

Hint 1: Start with Inspection Don’t create config files from scratch. First run kiro-cli settings list to see all available options and their current values. This shows you what’s configurable.

Hint 2: Use CLI Commands First Instead of editing JSON manually, use kiro-cli settings <key> <value> commands. This validates your input and prevents syntax errors. Example: kiro-cli settings chat.defaultModel "claude-sonnet-4".

Hint 3: Test Incrementally Change one setting at a time and verify it works with kiro chat. Add model override, test. Add telemetry disable, test. Build confidence before creating complex configs.

Hint 4: Verify with JSON Tools Use jq or python -m json.tool to validate your settings.json syntax:

cat ~/.config/kiro/settings.json | jq .

If this fails, your JSON is malformed.

---

Books That Will Help

Topic	Book	Chapter
Configuration best practices	“The Pragmatic Programmer” by Hunt & Thomas	Ch. 8: Pragmatic Projects
JSON structure and validation	“Effective Shell” by Dave Kerr	Ch. 13: Working with Data
Tool customization patterns	“Working Effectively with Legacy Code” by Feathers	Ch. 10: Configuration Management

---

Common Pitfalls & Debugging

Problem 1: “Kiro ignores my global settings”

• Why: Project-level settings override global ones
• Fix: Check if <project>/.kiro/settings.json exists and has conflicting values
• Quick test: cat .kiro/settings.json in your project directory

Problem 2: “Settings file causes Kiro to crash on startup”

• Why: Invalid JSON syntax (missing comma, extra bracket, unquoted string)
• Fix: Validate with jq . < ~/.config/kiro/settings.json or use kiro-cli settings commands
• Quick test: kiro-cli settings list should not error

Problem 3: “Knowledge base includes too many files”

• Why: Default patterns like * match everything including node_modules/
• Fix: Use specific patterns: ["*.py", "*.js", "!node_modules/**", "!build/**"]
• Quick test: kiro-cli settings knowledge.defaultIncludePatterns --get to inspect current patterns

Problem 4: “Steering file not loaded”

• Why: File path in config is wrong or file doesn’t exist
• Fix: Use absolute paths or paths relative to .kiro/ directory
• Quick test: kiro chat → ask “what are your current steering rules?” → verify file is mentioned

---

Definition of Done

• ~/.config/kiro/settings.json exists and is valid JSON
• Running kiro chat in any directory uses your default model (verify with greeting message or /settings command)
• Telemetry preference (on/off) persists across sessions
• Knowledge base is enabled and indexes expected file types
• Global steering file (if created) is loaded in all new sessions
• kiro-cli settings list shows all your customizations
• Settings can be exported as JSON and re-imported on a new machine
• You understand how to override global settings at project level

---