ai-development-team-agent-pack/.ai/skills/clean-code.md

Skill — Clean Code

Purpose

Write simple, readable, testable, maintainable code.

Principles

• Prefer clarity over cleverness.
• Prefer explicit contracts over implied behavior.
• Keep instructions short and routable.
• Use examples where they prevent mistakes.
• Avoid duplicating rules that belong in another file.
• Treat the Product Owner as the final authority.
• Make work testable.
• Capture durable lessons.

Process

1. Understand the task.
2. Load the smallest useful set of context files.
3. Identify assumptions.
4. Produce the requested artifact.
5. Validate against a checklist.
6. Suggest improvements only when justified.

Best Practices

• Use headings that agents can scan.
• Use checklists for repeatable work.
• Use tables for routing and decisions.
• Keep examples minimal and practical.
• Capture preconditions, postconditions, invariants, and failure modes when behavior matters.
• Store project-specific facts in project files.
• Store reusable rules in skill files.
• Store role behavior in agent files.
• Store process steps in workflow files.
• Store reusable document formats in templates.

Anti-Patterns

• Giant single instruction files.
• Conflicting rules in multiple places.
• Vague agent personas with no outputs.
• Uncontrolled self-modifying instructions.
• Rewriting standards without approval.
• Creating documentation no one will use.

Output Standard

Outputs should be:

• Complete enough to act on
• Concise enough to reuse
• Structured in Markdown
• Easy to review
• Easy to update

---

Self-Evolution Protocol

This file is allowed to improve over time, but only through a controlled change process.

When to propose an update

An agent may propose an update when it learns:

• A recurring mistake should be prevented.
• A better workflow has been proven useful.
• A project-specific convention has become stable.
• A prompt pattern produced better results.
• A tool, framework, library, or deployment rule changed.
• The Product Owner approved a new standard.

How to update this file

Agents must not silently rewrite this file. They must create an improvement proposal using:

./.ai/evolution/improvement-proposal-template.md

Every proposal must include:

• File to update
• Current problem
• Proposed change
• Reason
• Risk
• Rollback plan
• Product Owner approval status

Learning Log

Add durable lessons here only after they are proven useful.

Date	Lesson Learned	Change Made	Approved By
YYYY-MM-DD	Initial baseline created.	Created file.	Product Owner